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1. Introduction 

It was an explicit design goal of X Version 1 1 to specify mechanism, not policy. As a result, a 
client that converses with the server using the protocol defined by the X Window System Protocol, 
Version 1 1 may operate correctly in isolation but may not coexist properly with others sharing the 
same server. 

Being a good citizen in the X Version 1 1 world involves adhering to conventions that govern 
inter-client communications in the following areas: 

• Selection mechanism 

• Cut buffers 

• Window manager 

• Session manager 

• Manipulation of shared resources 

• Device color characterization 

This document proposes suitable conventions without attempting to enforce any particular user 
interface. To permit clients written in different languages to communicate, these conventions are 
expressed solely in terms of protocol operations, not in terms of their associated Xlib interfaces, 
which are probably more familiar. The binding of these operations to the Xlib interface for C and 
to the equivalent interfaces for other languages is the subject of other documents. 

1.1. Evolution of the Conventions 

In the interests of timely acceptance, the Inter-Client Communication Conventions Manual 
(ICCCM) covers only a minimal set of required conventions. These conventions will be added to 
and updated as appropriate, based on the experiences of the X Consortium. 

As far as possible, these conventions are upwardly compatible with those in the February 25, 

1988, draft that was distributed with the X Version 11, Release 2, of the software. In some areas, 
semantic problems were discovered with those conventions, and, thus, complete upward compati- 
bility could not be assured. These areas are noted in the text and are summarized in Appendix A. 

In the course of developing these conventions, a number of minor changes to the protocol were 
identified as desirable. They also are identified in the text, are summarized in Appendix B, and 
are offered as input to a future protocol revision process. If and when a protocol revision incorpo- 
rating these changes is undertaken, it is anticipated that the ICCCM will need to be revised. 
Because it is difficult to ensure that clients and servers are upgraded simultaneously, clients using 
the revised conventions should examine the minor protocol revision number and be prepared to 
use the older conventions when communicating with an older server. 

It is expected that these revisions will ensure that clients using the conventions appropriate to pro- 
tocol minor revision n will interoperate correctly with those that use the conventions appropriate 
to protocol minor revision n + 1 if the server supports both. 

1.2. Atoms 

Many of the conventions use atoms. To assist the reader, the following sections attempt to 
amplify the description of atoms that is provided in the protocol specification. 

1.2.1. What Are Atoms? 

At the conceptual level, atoms are unique names that clients can use to communicate information 
to each other. They can be thought of as a bundle of octets, like a string but without an encoding 
being specified. The elements are not necessarily ASCII characters, and no case folding 
happens. 1 

1 The comment in the protocol specification for Intern A tom that ISO Latin- 1 encoding should be used is in the nature of a convention; 
the server treats the string as a byte sequence. 


l 



Inter- Client Communication Conventions 


Xll, Release 6.4 


The protocol designers felt that passing these sequences of bytes back and forth across the wire 
would be too costly. Further, they thought it important that events as they appear on the wire have 
a fixed size (in fact, 32 bytes) and that because some events contain atoms, a fixed-size represen- 
tation for them was needed. 

To allow a fixed-size representation, a protocol request (InternAtom) was provided to register a 
byte sequence with the server, which returns a 32-bit value (with the top three bits zero) that maps 
to the byte sequence. The inverse operator is also available (GetAtomName). 

1.2.2. Predefined Atoms 

The protocol specifies a number of atoms as being predefined: 

Predefined atoms are not strictly necessary and may not be useful in all environments, 
but they will eliminate many InternAtom requests in most applications. Note that 
they are predefined only in the sense of having numeric values, not in the sense of hav- 
ing required semantics. 

Predefined atoms are an implementation trick to avoid the cost of interning many of the atoms 
that are expected to be used during the startup phase of all applications. The results of the 
InternAtom requests, which require a handshake, can be assumed a priori. 

Language interfaces should probably cache the atom-name mappings and get them only when 
required. The CLX interface, for instance, makes no distinction between predefined atoms and 
other atoms; all atoms are viewed as symbols at the interface. However, a CLX implementation 
will typically keep a symbol or atom cache and will typically initialize this cache with the prede- 
fined atoms. 

1.2.3. Naming Conventions 

The built-in atoms are composed of uppercase ASCII characters with the logical words separated 
by an underscore character (_), for example, WM_ICON_NAME. The protocol specification rec- 
ommends that atoms used for private vendor-specific reasons should begin with an underscore. 

To prevent conflicts among organizations, additional prefixes should be chosen (for example, 
_DEC_WM_DECORATION_GEOMETRY). 

The names were chosen in this fashion to make it easy to use them in a natural way within LISR 
Keyword constructors allow the programmer to specify the atoms as LISP atoms. If the atoms 
were not all uppercase, special quoting conventions would have to be used. 

1.2.4. Semantics 

The core protocol imposes no semantics on atoms except as they are used in FONTPROP struc- 
tures. For further information on FONTPROP semantics, see the X Logical Font Description 
Conventions. ■ 

1.2.5. Name Spaces 

The protocol defines six distinct spaces in which atoms are interpreted. Any particular atom may 
or may not have some valid interpretation with respect to each of these name spaces. 


Space 

Briefly 

, Examples 

Property name 
Property type 

Selection name 
Selection target 

Font property 
ClientMessage type 

Name 

Type 

Selection 

Target 

WM HINTS, WM_NAME, RGB_BEST_MAP, . 
WM HINTS, CURSOR, RGB_COLOR_MAP, .. 
PRIMARY, SECONDARY, CLIPBOARD 

FILE NAME, POSTSCRIPT, PIXMAP, ... 
QUAD_WIDTH, POINT_SIZE, ... 

WM SAVE YOURSELF, _DEC_SAVE_EDITS, 
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1.2.6. Discriminated Names 

Sometimes a protocol requires an arbitrary number of similar objects that need unique names 
(usually because the objects are created dynamically, so that names cannot be invented in 
advance). For example, a colormap-generating program might use the selection mechanism to 
offer colormaps for each screen and so needs a selection name for each screen. Such names are 
called “discriminated names” and are discriminated by some entity. This entity can be: 

A screen 

An X resource (a window, a colormap, a visual, etc.) 

A client 

If it is only necessary to generate a fixed set of names for each value of the discriminating entity, 
then the discriminated names are formed by suffixing an ordinary name according to the value of 
the entity. 

If name is a descriptive portion for the name, d is a decimal number with no leading zeroes, and x 
is a hexadecimal number with exactly 8 digits, and using uppercase letters, then such discrimi- 
nated names shall have the form: 

Name Discriminated by Form Example 

screen number nameJSd WM_COMMS_S2 

X resource name_Rx GROUP_LEADER_R1234ABCD 

To discriminate a name by client, use an X resource ID created by that client. This resource can 
be of any type. 

Sometimes it is simply necessary to generate a unique set of names (for example, for the proper- 
ties on a window used by a MULTIPLE selection). These names should have the form: 

U d (e.g., UO U1 U2 U3 ...) 

if the names stand totally alone, and the form: 

nameJJd (e.g., FOOJUO BAR_U0 FOOJUl BAR_U1 ...) 

if they come in sets (here there are two sets, named “FOO” and “BAR”). The stand-alone U d 
form should be used only if it is clear that the module using it has complete control over the rele- 
vant namespace or has the active cooperation of all other entities that might also use these names. 
(Naming properties on a window created specifically for a particular selection is such a use; nam- 
ing properties on the root window is almost certainly not.) 

In a particularly difficult case, it might be necessary to combine both forms of discrimination. If 
this happens, the U form should come after the other form, thus: 

FOO_R 1234567 8_U23 

Rationale 

Existing protocols will not be changed to use these naming conventions, because 
doing so will cause too much disruption. However, it is expected that future proto- 
cols — both standard and private — will use these conventions. 


2. Peer-to-Peer Communication by Means of Selections 

Selections are the primary mechanism that X Version 1 1 defines for the exchange of information 
between clients, for example, by cutting and pasting between windows. Note that there can be an 
arbitrary number of selections (each named by an atom) and that they are global to the server. 
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Section 2.6 discusses the choice of an atom. Each selection is owned by a client and is attached 
to a window. 

Selections communicate between an owner and a requestor. The owner has the data representing 
the value of its selection, and the requestor receives it. A requestor wishing to obtain the value of 
a selection provides the following: 

• The name of the selection 

• The name of a property 

• A window 

• The atom representing the data type required 

• Optionally, some parameters for the request 

If the selection is currently owned, the owner receives an event and is expected to do the follow- 
ing: 

• Convert the contents of the selection to the requested data type 

• Place this data in the named property on the named window 

• Send the requestor an event to let it know the property is available 

Clients are strongly encouraged to use this mechanism. In particular, displaying text in a perma- 
nent window without providing the ability to select and convert it into a string is definitely con- 
sidered antisocial. 

Note that all data transferred between an owner and a requestor must usually go by means of the 
server in an X Version 1 1 environment. A client cannot assume that another client can open the 
same files or even communicate directly. The other client may be talking to the server by means 
of a completely different networking mechanism (for example, one client might be DECnet and 
the other TCP/IP). Thus, passing indirect references to data (such as, file names, host names, and 
port numbers) is permitted only if both clients specifically agree. 

2.1. Acquiring Selection Ownership 

A client wishing to acquire ownership of a particular selection should call SetSelectionOwner, 
which is defined as follows: 

SetSelectionOwner 

selection : ATOM 

owner : WINDOW or None 

time : TIMESTAMP or CurrentTime 


The client should set the specified selection to the atom that represents the selection, set the speci- 
fied owner to some window that the client created, and set the specified time to some time 
between the current last-change time of the selection concerned and the current server time. This 
time value usually will be obtained from the timestamp of the event that triggers the acquisition of 
the selection. Clients should not set the time value to CurrentTime, because if they do so, they 
have no way of finding when they gained ownership of the selection. Clients must use a window 
they created so that requestors can route events to the owner of the selection. 2 


2 At present, no part of the protocol requires requestors to send events to the owner of a selection. This restriction is imposed to prepare 
for possible future extensions. 


4 



Inter- Client Communication Conventions 


XI 1, Release 6.4 


Convention 

Clients attempting to acquire a selection must set the time value of the SetSelection- 
Owner request to the timestamp of the event triggering the acquisition attempt, not 
to CurrentTime. A zero-length append to a property is a way to obtain a timestamp 
for this purpose; the timestamp is in the corresponding PropertyNotify event. 

If the time in the SetSelectionOwner request is in the future relative to the server’s current time 
or is in the past relative to the last time the specified selection changed hands, the SetSelec- 
tionOwner request appears to the client to succeed, but ownership is not actually transferred. 

Because clients cannot name other clients directly, the specified owner window is used to refer to 
the owning client in the replies to GetSelectionOwner, in SelectionRequest and Selection- 
Clear events, and possibly as a place to put properties describing the selection in question. To 
discover the owner of a particular selection, a client should invoke GetSelectionOwner, which is 
defined as follows: 


u 


GetSelectionOwner 

selection : ATOM 

— > 

owner: WINDOW or None 


Convention 

Clients are expected to provide some visible confirmation of selection ownership. To 
make this feedback reliable, a client must perform a sequence like the following: 

SetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp) 
owner = GetSelectionOwner(selection=PRIMARY) 
if (owner != Window) Failure 

If the SetSelectionOwner request succeeds (not merely appears to succeed), the client that issues 
it is recorded by the server as being the owner of the selection for the time period starting at the 
specified time. 

2.2. Responsibilities of the Selection Owner 

When a requestor wants the value of a selection, the owner receives a SelectionRequest event, 
which is defined as follows: 

SelectionRequest 

owner: WINDOW 

selection: ATOM 

target: ATOM 

property: ATOM or None 

requestor: WINDOW 

time: TIMESTAMP or CurrentTime 

The specified owner and selection will be the values that were specified in the SetSelection- 
Owner request. The owner should compare the timestamp with the period it has owned the 
selection and, if the time is outside, refuse the SelectionRequest by sending the requestor win- 
dow a SelectionNotify event with the property set to None (by means of a SendEvent request 
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with an empty event mask). 

More advanced selection owners are free to maintain a history of the value of the selection and to 
respond to requests for the value of the selection during periods they owned it even though they 
do not own it now. 

If the specified property is None, the requestor is an obsolete client. Owners are encouraged to 
support these clients by using the specified target atom as the property name to be used for the 
reply. 

Otherwise, the owner should use the target to decide the form into which the selection should be 
converted. Some targets may be defined such that requestors can pass parameters along with the 
request. The owner will find these parameters in the property named in the selection request. 

The type, format, and contents of this property are dependent upon the definition of the target. If 
the target is not defined to have parameters, the owner should ignore the property if it is present. 
If the selection cannot be converted into a form based on the target (and parameters, if any), the 
owner should refuse the SelectionRequest as previously described. 

If the specified property is not None, the owner should place the data resulting from converting 
the selection into the specified property on the requestor window and should set the property’s 
type to some appropriate value, which need not be the same as the specified target. 

Convention 

All properties used to reply to SelectionRequest events must be placed on the 
requestor window. 

In either case, if the data comprising the selection cannot be stored on the requestor window (for 
example, because the server cannot provide sufficient memory), the owner must refuse the 
SelectionRequest, as previously described. See also section 2.5. 

If the property is successfully stored, the owner should acknowledge the successful conversion by 
sending the requestor window a SelectionNotify event (by means of a SendEvent request with 
an empty mask). SelectionNotify is defined as follows: 

SelectionNotify 

requestor'. WINDOW 

selection, target'. ATOM 

property-. ATOM or None 

time : TIMESTAMP or CurrentTime 

The owner should set the specified selection, target, time, and property arguments to the values 
received in the SelectionRequest event. (Note that setting the property argument to None indi- 
cates that the conversion requested could not be made.) 

Convention 

The selection, target, time, and property arguments in the SelectionNotify event 
should be set to the values received in the SelectionRequest event. 

If the owner receives more than one SelectionRequest event with the same requestor, selection, 
target, and timestamp it must respond to them in the same order in which they were received. 
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Rationale 

It is possible for a requestor to have multiple outstanding requests that use the same 
requestor window, selection, target, and timestamp, and that differ only in the prop- 
erty. If this occurs, and one of the conversion requests fails, the resulting Selection- 
Notify event will have its property argument set to None . This may make it impos- 
sible for the requestor to determine which conversion request had failed, unless the 
requests are responded to in order. 

The data stored in the property must eventually be deleted. A convention is needed to assign the 
responsibility for doing so. 


Convention 

Selection requestors are responsible for deleting properties whose names they receive 
in SelectionNotify events (see section 2.4) or in properties with type MULTIPLE. 

A selection owner will often need confirmation that the data comprising the selection has actually 
been transferred. (For example, if the operation has side effects on the owner’s internal data 
structures, these should not take place until the requestor has indicated that it has successfully 
received the data.) Owners should express interest in PropertyNotify events for the specified 
requestor window and wait until the property in the SelectionNotify event has been deleted 
before assuming that the selection data has been transferred. For the MULTIPLE request, if the 
different conversions require separate confirmation, the selection owner can also watch for the 
deletion of the individual properties named in the property in the SelectionNotify event. 

When some other client acquires a selection, the previous owner receives a SelectionClear event, 
which is defined as follows: 

SelectionClear 

owner: WINDOW 
selection : ATOM 
time: TIMESTAMP 


The timestamp argument is the time at which the ownership changed hands, and the owner argu- 
ment is the window the previous owner specified in its SetSelectionOwner request. 

If an owner loses ownership while it has a transfer in progress (that is, before it receives notifica- 
tion that the requestor has received all the data), it must continue to service the ongoing transfer 
until it is complete. 

If the selection value completely changes, but the owner happens to be the same client (for exam- 
ple, selecting a totally different piece of text in the same xterm as before), then the client should 
reacquire the selection ownership as if it were not the owner, providing a new timestamp. If the 
selection value is modified, but can still reasonably be viewed as the same selected object, 3 the 
owner should take no action. 

2.3. Giving Up Selection Ownership 

Clients may either give up selection ownership voluntarily or lose it forcibly as the result of some 
other client’s actions. 


3 The division between these two cases is a matter of judgment on the part of the software developer. 
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2.3.1. Voluntarily Giving Up Selection Ownership 

To relinquish ownership of a selection voluntarily, a client should execute a SetSelectionOwner 
request for that selection atom, with owner specified as None and the time specified as the time- 
stamp that was used to acquire the selection. 

Alternatively, the client may destroy the window used as the owner value of the SetSelection- 
Owner request, or the client may terminate. In both cases, the ownership of the selection 
involved will revert to None . 

2.3.2. Forcibly Giving Up Selection Ownership 

If a client gives up ownership of a selection or if some other client executes a SetSelection- 
Owner for it and thus reassigns it forcibly, the previous owner will receive a SelectionClear 
event. For the definition of a SelectionClear event, see section 2.2. 

The timestamp is the time the selection changed hands. The specified owner is the window that 
was specified by the current owner in its SetSelectionOwner request. 

2.4. Requesting a Selection 

A client that wishes to obtain the value of a selection in a particular form (the requestor) issues a 
ConvertSelection request, which is defined as follows: 

ConvertSelection 

selection, target : ATOM 
property: ATOM or None 
requestor: WINDOW 
time : TIMESTAMP or CurrentTime 


The selection argument specifies the particular selection involved, and the target argument speci- 
fies the required form of the information. For information about the choice of suitable atoms to 
use, see section 2.6. The requestor should set the requestor argument to a window that it created; 
the owner will place the reply property there. The requestor should set the time argument to the 
timestamp on the event that triggered the request for the selection value. Note that clients should 
not specify CurrentTime . 

Convention 

Clients should not use CurrentTime for the time argument of a ConvertSelection 
request. Instead, they should use the timestamp of the event that caused the request 
to be made. 

The requestor should set the property argument to the name of a property that the owner can use 
to report the value of the selection. Requestors should ensure that the named property does not 
exist on the window before issuing the ConvertSelection request. 4 The exception to this rule is 
when the requestor intends to pass parameters with the request (see below). 

Rationale 

It is necessary for requestors to delete the property before issuing the request so that 
the target can later be extended to take parameters without introducing an incompati- 
bility. Also note that the requestor of a selection need not know the client that owns 
the selection nor the window on which the selection was acquired. 


4 This requirement is new in version 2.0, and, in general, existing clients do not conform to this requirement. To prevent these clients 
from breaking, no existing targets should be extended to take parameters until sufficient time has passed for clients to be updated. Note that 
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Some targets may be defined such that requestors can pass parameters along with the request. If 
the requestor wishes to provide parameters to a request, they should be placed in the specified 
property on the requestor window before the requestor issues the ConvertSelection request, and 
this property should be named in the request. 

Some targets may be defined so that parameters are optional. If no parameters are to be supplied 
with the request of such a target, the requestor must ensure that the property does not exist before 
issuing the ConvertSelection request. 

The protocol allows the property field to be set to None, in which case the owner is supposed to 
choose a property name. However, it is difficult for the owner to make this choice safely. 

Conventions 

1. Requestors should not use None for the property argument of a ConvertSelection 
request. 

2. Owners receiving ConvertSelection requests with a property argument of None are 
talking to an obsolete client. They should choose the target atom as the property 
name to be used for the reply. 

The result of the ConvertSelection request is that a SelectionNotify event will be received. For 
the definition of a SelectionNotify event, see section 2.2. 

The requestor, selection, time, and target arguments will be the same as those on the ConvertSe- 
lection request. 

If the property argument is None , the conversion has been refused. This can mean either that 
there is no owner for the selection, that the owner does not support the conversion implied by the 
target, or that the server did not have sufficient space to accommodate the data. 

If the property argument is not None, then that property will exist on the requestor window. The 
value of the selection can be retrieved from this property by using the GetProperty request, 
which is defined as follows: 

GetProperty 

window : WINDOW 
property. ATOM 

type : ATOM or AnyPropertyType 
long-offset, long-length : CARD32 
delete : BOOL 


type: ATOM or None 
format: {0, 8, 16, 32} 
bytes-after: CARD32 

value: LISTofINT8 or LISTofINT16 or LISTofINT32 


When using GetProperty to retrieve the value of a selection, the property argument should be set 
to the corresponding value in the SelectionNotify event. Because the requestor has no way of 
knowing beforehand what type the selection owner will use, the type argument should be set to 
AnyPropertyType . Several GetProperty requests may be needed to retrieve all the data in the 
selection; each should set the long-offset argument to the amount of data received so far, and the 
size argument to some reasonable buffer size (see section 2.5). If the returned value of bytes-after 
is zero, the whole property has been transferred. 


the MULTIPLE target was defined to take parameters in version 1.0 and its definition is not changing. There is thus no conformance prob- 
lem with MULTIPLE. 
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Once all the data in the selection has been retrieved (which may require getting the values of sev- 
eral properties — see section 2.7), the requestor should delete the property in the SelectionNotify 
request by using a GetProperty request with the delete argument set to True . As previously dis- 
cussed, the owner has no way of knowing when the data has been transferred to the requestor 
unless the property is removed. 

Convention 

The requestor must delete the property named in the SelectionNotify once all the 
data has been retrieved. The requestor should invoke either DeleteProperty or 
GetProperty (delete==True) after it has successfully retrieved all the data in the 
selection. For further information, see section 2.5. 


2.5. Large Data Transfers 

Selections can get large, which poses two problems: 

• Transferring large amounts of data to the server is expensive. 

• All servers will have limits on the amount of data that can be stored in properties. Exceed- 
ing this limit will result in an Alloc error on the ChangeProperty request that the selection 
owner uses to store the data. 

The problem of limited server resources is addressed by the following conventions: 

Conventions 

1. Selection owners should transfer the data describing a large selection (relative to the 
maximum-request-size they received in the connection handshake) using the INCR 
property mechanism (see section 2.7.2). 

2. Any client using SetSelectionOwner to acquire selection ownership should arrange 
to process Alloc errors in property change requests. For clients using Xlib, this 
involves using the XSetErrorHandler function to override the default handler. 

3. A selection owner must confirm that no Alloc error occurred while storing the prop- 
erties for a selection before replying with a confirming SelectionNotify event. 

4. When storing large amounts of data (relative to maximum-request-size), clients 
should use a sequence of ChangeProperty (mode==Append) requests for reasonable 
quantities of data. This avoids locking servers up and limits the waste of data an 
Alloc error would cause. 

5. If an Alloc error occurs during the storing of the selection data, all properties stored 
for this selection should be deleted and the ConvertSelection request should be 
refused (see section 2.2). 

6. To avoid locking servers up for inordinate lengths of time, requestors retrieving large 
quantities of data from a property should perform a series of GetProperty requests, 
each asking for a reasonable amount of data. 

Advice to Implementors 

Single-threaded servers should take care to avoid locking up during large data trans- 
fers. 


2.6. Use of Selection Atoms 

Defining a new atom consumes resources in the server that are not released until the server reini- 
tializes. Thus, reducing the need for newly min ted atoms is an important goal for the use of the 
selection atoms. 
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2.6.1. Selection Atoms 

There can be an arbitrary number of selections, each named by an atom. To conform with the 
inter-client conventions, however, clients need deal with only these three selections: 

• PRIMARY 

• SECONDARY 

• CLIPBOARD 

Other selections may be used freely for private communication among related groups of clients. 

2.6.1.1. The PRIMARY Selection 

The selection named by the atom PRIMARY is used for all commands that take only a single 
argument and is the principal means of communication between clients that use the selection 
mechanism. 

2.6.1.2. The SECONDARY Selection 

The selection named by the atom SECONDARY is used: 

• As the second argument to commands taking two arguments (for example, “exchange pri- 
mary and secondary selections”) 

• Asa means of obtaining data when there is a primary selection and the user does not want to 
disturb it 

2.6.1.3. The CLIPBOARD Selection 

The selection named by the atom CLIPBOARD is used to hold data that is being transferred 
between clients, that is, data that usually is being cut and then pasted or copied and then pasted. 
Whenever a client wants to transfer data to the clipboard: 

• It should assert ownership of the CLIPBOARD. 

• If it succeeds in acquiring ownership, it should be prepared to respond to a request for the 
contents of the CLIPBOARD in the usual way (retaining the data to be able to return it). 

The request may be generated by the clipboard client described below. 

• If it fails to acquire ownership, a cutting client should not actually perform the cut or provide 
feedback that would suggest that it has actually transferred data to the clipboard. 

The owner should repeat this process whenever the data to be transferred would change. 

Clients wanting to paste data from the clipboard should request the contents of the CLIPBOARD 
selection in the usual way. 

Except while a client is actually deleting or copying data, the owner of the CLIPBOARD selec- 
tion may be a single, special client implemented for the purpose. This client maintains the con- 
tent of the clipboard up-to-date and responds to requests for data from the clipboard as follows: 

• It should assert ownership of the CLIPBOARD selection and reassert it any time the clip- 
board data changes. 

• If it loses the selection (because another client has some new data for the clipboard), it 
should: 

- Obtain the contents of the selection from the new owner by using the timestamp in the 
SelectionClear event. 

- Attempt to reassert ownership of the CLIPBOARD selection by using the same time- 
stamp. 

- Restart the process using a newly acquired timestamp if this attempt fails. This time- 
stamp should be obtained by asking the current owner of the CLIPBOARD selection 
to convert it to a TIMESTAMP. If this conversion is refused or if the same timestamp 
is received twice, the clipboard client should acquire a fresh timestamp in the usual 
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way (for example by a zero-length append to a property). 

• It should respond to requests for the CLIPBOARD contents in the usual way. 

A special CLIPBOARD client is not necessary. The protocol used by the cutting client and the 
pasting client is the same whether the CLIPBOARD client is running or not. The reasons for run- 
ning the special client include: 

• Stability - If the cutting client were to crash or terminate, the clipboard value would still be 
available. 

• Feedback - The clipboard client can display the contents of the clipboard. 

• Simplicity - A client deleting data does not have to retain it for so long, thus reducing the 
chance of race conditions causing problems. 

The reasons not to run the clipboard client include: 

• Performance - Data is transferred only if it is actually required (that is, when some client 
actually wants the data). 

• Flexibility - The clipboard data may be available as more than one target. 

2.6.2. Target Atoms 

The atom that a requestor supplies as the target of a ConvertSelection request determines the 
form of the data supplied. The set of such atoms is extensible, but a generally accepted base set 
of target atoms is needed. As a starting point for this, the following table contains those that have 
been suggested so far. 

Atom Type Data Received 


ADOBE_PORTABLE_DOCUMENT_FORMAT 



STRING 

[1] 

APPLE_PICT 

APPLE_PICT 

[2] 

BACKGROUND 

PIXEL 

A list of pixel values 

BITMAP 

BITMAP 

A list of bitmap IDs 

CHARACTER POSITION 

SPAN 

The start and end of the selection in bytes 

CLASS 

TEXT 

(see section 4. 1.2.5) 

CLIENT JWINDOW 

WINDOW 

Any top-level window owned by the selection 



owner 

COLORMAP 

COLORMAP 

A list of colormap IDs 

COLUMN NUMBER 

SPAN 

The start and end column numbers 

COMPOUND_TEXT 

COMPOUND_TEXT 

Compound Text 

DELETE 

NULL 

(see section 2.6.3. 1) 

DRAWABLE 

DRAWABLE 

A list of drawable IDs 

ENCAPSULATED_POSTSCRIPT 



STRING 

[3], Appendix H 5 

ENCAPSULATED_POSTSCRIPT_INTERCHANGE 



STRING 

[3], Appendix H 

FILE NAME 

TEXT 

The full path name of a file 

FOREGROUND 

PIXEL 

A list of pixel values 

HOST_NAME 

TEXT 

(see section 4. 1.2.9) 

INSERT PROPERTY 

NULL 

(see section 2.6.3. 3) 

INSERT SELECTION 

NULL 

(see section 2. 6. 3. 2) 

LENGTH 

INTEGER 

The number of bytes in the selection 6 

LINE_NUMBER 

SPAN 

The start and end line numbers 
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Atom 

Type 

Data Received 

LIST LENGTH 

INTEGER 

The number of disjoint parts of the selection 

MODULE 

TEXT 

The name of the selected procedure 

MULTIPLE 

ATOM PAIR 

(see the discussion that follows) 

NAME 

TEXT 

(see section 4. 1.2.1) 

ODIF 

TEXT 

ISO Office Document Interchange Format 

OWNER OS 

TEXT 

The operating system of the owner client 

PIXMAP 

PIXMAP 5 6 7 

A list of pixmap IDs 

POSTSCRIPT 

STRING 

[3] 

PROCEDURE 

TEXT 

The name of the selected procedure 

PROCESS 

INTEGER, TEXT 

The process ID of the owner 

STRING 

STRING 

ISO Latin- 1 (+TAB+NEWLINE) text 

TARGETS 

ATOM 

A list of valid target atoms 

TASK 

INTEGER, TEXT 

The task ID of the owner 

TEXT 

TEXT 

The text in the owner’s choice of encoding 

TIMESTAMP 

INTEGER 

The timestamp used to acquire the selection 

USER 

TEXT 

The name of the user running the owner 


References: 

[1] Adobe Systems, Incorporated. Portable Document Format Reference Manual. Reading, 
MA, Addison- Wesley, ISBN 0-20 1 -62628-4. 

[2] Apple Computer, Incorporated. Inside Macintosh, Volume V. Chapter 4, “Color 
QuickDraw,” Color Picture Format. ISBN 0-201-17719-6. 

[3] Adobe Systems, Incorporated. PostScript Language Reference Manual. Reading, MA, 
Addison-Wesley, ISBN 0-201-18127-4. 

It is expected that this table will grow over time. 

Selection owners are required to support the following targets. All other targets are optional. 

• TARGETS - The owner should return a list of atoms that represent the targets for which an 
attempt to convert the current selection will succeed (barring unforseeable problems such as 
Alloc errors). This list should include all the required atoms. 

• MULTIPLE - The MULTIPLE target atom is valid only when a property is specified on the 
ConvertSelection request. If the property argument in the SelectionRequest event is None 
and the target is MULTIPLE, it should be refused. 

When a selection owner receives a SelectionRequest (target==MULTIPLE) request, the 
contents of the property named in the request will be a list of atom pairs: the first atom nam- 
ing a target and the second naming a property (None is not valid here). The effect should be 
as if the owner had received a sequence of SelectionRequest events (one for each atom pair) 
except that: 

- The owner should reply with a SelectionNotify only when all the requested conver- 
sions have been performed. 


5 Earlier versions of this document erroneously specified that conversion of the PIXMAP target returns a property of type DRAWABLE 
instead of PIXMAP. Implementors should be aware of this and may want to support the DRAWABLE type as well to allow for compatibility 
with older clients. 

6 The targets ENCAPSULATED_POSTSCRIPT and ENCAPSULATED_POSTSCRIPT_INTERCHANGE are equivalent to the targets 
_ADOBE_EPS and _ADOBE_EPSI (respectively) that appear in the selection targets registry. The _ADOBE_ targets are deprecated, but 
clients are encouraged to continue to support them for backward compatibility. 

7 This definition is ambiguous, as the selection may be converted into any of several targets that may return differing amounts of data. 
The requestor has no way of knowing which, if any, of these targets corresponds to the result of LENGTH. Clients are advised that no guar- 
antees can be made about the result of a conversion to LENGTH; its use is thus deprecated. 
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- If the owner fails to convert the target named by an atom in the MULTIPLE property, 
it should replace that atom in the property with None. 

Convention 

The entries in a MULTIPLE property must be processed in the order they appear 
in the property. For further information, see section 2.6.3. 

The requestor should delete each individual property when it has copied the data from that 
conversion, and the property specified in the MULTIPLE request when it has copied all the 
data. 

The requests are otherwise to be processed independently, and they should succeed or fail 
independently. The MULTIPLE target is an optimization that reduces the amount of proto- 
col traffic between the owner and the requestor; it is not a transaction mechanism. For 
example, a client may issue a MULTIPLE request with two targets: a data target and the 
DELETE target. The DELETE target will still be processed even if the conversion of the 
data target fails. 

• TIMESTAMP - To avoid some race conditions, it is important that requestors be able to dis- 
cover the timestamp the owner used to acquire ownership. Until and unless the protocol is 
changed so that a GetSelectionOwner request returns the timestamp used to acquire owner- 
ship, selection owners must support conversion to TIMESTAMP, returning the timestamp 
they used to obtain the selection. 

2.6.3. Selection Targets with Side Effects 

Some targets (for example, DELETE) have side effects. To render these targets unambiguous, the 
entries in a MULTIPLE property must be processed in the order that they appear in the property. 

In general, targets with side effects will return no information, that is, they will return a zero 
length property of type NULL. (Type NULL means the result of InternAtom on the string 
“NULL”, not the value zero.) In all cases, the requested side effect must be performed before the 
conversion is accepted. If the requested side effect cannot be performed, the corresponding con- 
version request must be refused. 


Conventions 

1. Targets with side effects should return no information (that is, they should have a 
zero-length property of type NULL). 

2. The side effect of a target must be performed before the conversion is accepted. 

3. If the side effect of a target cannot be performed, the corresponding conversion 
request must be refused. 


Problem 

The need to delay responding to the ConvertSelection request until a further conver- 
sion has succeeded poses problems for the Intrinsics interface that need to be 
addressed. 

These side-effect targets are used to implement operations such as “exchange PRIMARY and 
SECONDARY selections.” 

2.6.3.I. DELETE 

When the owner of a selection receives a request to convert it to DELETE, it should delete the 
corresponding selection (whatever doing so means for its internal data structures) and return a 
zero-length property of type NULL if the deletion was successful. 
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2.6.3.2. INSERT_SELECTION 

When the owner of a selection receives a request to convert it to INSERT_SELECTION, the 
property named will be of type ATOM_PAIR. The first atom will name a selection, and the sec- 
ond will name a target. The owner should use the selection mechanism to convert the named 
selection into the named target and should insert it at the location of the selection for which it got 
the INSERT_SELECTION request (whatever doing so means for its internal data structures). 

2.6.3.3. INSERT_PROPERTY 

When the owner of a selection receives a request to convert it to INSERT_PROPERTY, it should 
insert the property named in the request at the location of the selection for which it got the 
INSERT_SELECTION request (whatever doing so means for its internal data structures). 

2.7. Use of Selection Properties 

The names of the properties used in selection data transfer are chosen by the requestor. The use 
of None property fields in ConvertSelection requests (which request the selection owner to 
choose a name) is not permitted by these conventions. 

The selection owner always chooses the type of the property in the selection data transfer. Some 
types have special semantics assigned by convention, and these are reviewed in the following sec- 
tions. 

In all cases, a request for conversion to a target should return either a property of one of the types 
listed in the previous table for that target or a property of type INCR and then a property of one of 
the listed types. 

Certain selection properties may contain resource IDs. The selection owner should ensure that 
the resource is not destroyed and that its contents are not changed until after the selection transfer 
is complete. Requestors that rely on the existence or on the proper contents of a resource must 
operate on the resource (for example, by copying the contents of a pixmap) before deleting the 
selection property. 

The selection owner will return a list of zero or more items of the type indicated by the property 
type. In general, the number of items in the list will correspond to the number of disjoint parts of 
the selection. Some targets (for example, side-effect targets) will be of length zero irrespective of 
the number of disjoint selection parts. In the case of fixed-size items, the requestor may deter- 
mine the number of items by the property size. Selection property types are listed in the table 
below. For variable-length items such as text, the separators are also listed. 


Type Atom 

Format 

Separator 

APPLE PICT 

8 

Self-sizing 

ATOM 

32 

Fixed-size 

ATOM_PAER 

32 

Fixed-size 

BITMAP 

32 

Fixed-size 

C STRING 

8 

Zero 

COLORMAP 

32 

Fixed-size 

COMPOUND TEXT 

8 

Zero 

DRAWABLE 

32 

Fixed-size 

INCR 

32 

Fixed-size 

INTEGER 

32 

Fixed-size 

PIXEL 

32 

Fixed-size 

PIXMAP 

32 

Fixed-size 

SPAN 

32 

Fixed-size 

STRING 

8 

Zero 
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Type Atom Format Separator 

WINDOW 32 Fixed-size 


It is expected that this table will grow over time. 

2.7.1. TEXT Properties 

In general, the encoding for the characters in a text string property is specified by its type. It is 
highly desirable for there to be a simple, invertible mapping between string property types and 
any character set names embedded within font names in any font naming standard adopted by the 
Consortium. 

The atom TEXT is a polymorphic target. Requesting conversion into TEXT will convert into 
whatever encoding is convenient for the owner. The encoding chosen will be indicated by the 
type of the property returned. TEXT is not defined as a type; it will never be the returned type 
from a selection conversion request. 

If the requestor wants the owner to return the contents of the selection in a specific encoding, it 
should request conversion into the name of that encoding. 

In the table in section 2.6.2, the word TEXT (in the Type column) is used to indicate one of the 
registered encoding names. The type would not actually be TEXT; it would be STRING or some 
other ATOM naming the encoding chosen by the owner. 

STRING as a type or a target specifies the ISO Latin- 1 character set plus the control characters 
TAB (octal 11) and NEWLINE (octal 12). The spacing interpretation of TAB is context depen- 
dent. Other ASCII control characters are explicitly not included in STRING at the present time. 

COMPOUND_TEXT as a type or a target specifies the Compound Text interchange format; see 
the Compound Text Encoding. 

There are some text objects where the source or intended user, as the case may be, does not have a 
specific character set for the text, but instead merely requires a zero-terminated sequence of bytes 
with no other restriction; no element of the selection mechanism may assume that any byte value 
is forbidden or that any two differing sequences are equivalent. 8 For these objects, the type 
C_STRING should be used. 


Rationale 

An example of the need for C_STRING is to transmit the names of files; many oper- 
ating systems do not interpret filenames as having a character set. For example, the 
same character string uses a different sequence of bytes in ASCII and EBCDIC, and 
so most operating systems see these as different filenames and offer no way to treat 
them as the same. Thus no character-set based property type is suitable. 

Type STRING, COMPOUND_TEXT, and C_STRING properties will consist of a list of elements 
separated by null characters; other encodings will need to specify an appropriate list format. 

2.7.2. INCR Properties 

Requestors may receive a property of type INCR 9 in response to any target that results in selec- 
tion data. This indicates that the owner will send the actual data incrementally. The contents of 
the INCR property will be an integer, which represents a lower bound on the number of bytes of 

8 Note that this is different from STRING, where many byte values are forbidden, and from COMPOUND_TEXT, where, for example, 
inserting the sequence 27, 40, 66 (designate ASCII into GL) at the start does not alter the meaning. 

9 These properties were called INCREMENTAL in an earlier draft. The protocol for using them has changed, and so the name has 
changed to avoid confusion. 
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data in the selection. The requestor and the selection owner transfer the data in the selection in 
the following manner. 

The selection requestor starts the transfer process by deleting the (type==INCR) property forming 
the reply to the selection. 

The selection owner then: 

• Appends the data in suitable-size chunks to the same property on the same window as the 
selection reply with a type corresponding to the actual type of the converted selection. The 
size should be less than the maximum-request-size in the connection handshake. 

• Waits between each append for a PropertyNotify (state— Deleted) event that shows that the 
requestor has read the data. The reason for doing this is to limit the consumption of space in 
the server. 

• Waits (after the entire data has been transferred to the server) until a 
PropertyNotify(state==Deleted) event that shows that the data has been read by the 
requestor and then writes zero-length data to the property. 

The selection requestor: 

• Waits for the SelectionNotify event. 

• Loops: 

- Retrieving data using GetProperty with the delete argument True . 

- Waiting for a PropertyNotify with the state argument New Value . 

• Waits until the property named by the PropertyNotify event is zero-length. 

• Deletes the zero-length property. 

The type of the converted selection is the type of the first partial property. The remaining partial 
properties must have the same type. 

2.7.3. DRAWABLE Properties 

Requestors may receive properties of type PIXMAP, BITMAP, DRAWABLE, or WINDOW, 
which contain an appropriate ID. While information about these drawables is available from the 
server by means of the GetGeometry request, the following items are not: 

• Foreground pixel 

• Background pixel 

• Colormap ID 

In general, requestors converting into targets whose returned type in the table in section 2.6.2 is 
one of the DRAWABLE types should expect to convert also into the following targets (using the 
MULTIPLE mechanism): 

• FOREGROUND returns a PIXEL value. 

• BACKGROUND returns a PIXEL value. 

• COLORMAP returns a colormap ID. 

2.7.4. SPAN Properties 

Properties with type SPAN contain a list of cardinal-pairs with the length of the cardinals deter- 
mined by the format. The first specifies the starting position, and the second specifies the ending 
position plus one. The base is zero. If they are the same, the span is zero-length and is before the 
specified position. The units are implied by the target atom, such as LINE_NUMBER or CHAR- 
ACTER_POSITION. 
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2.8. Manager Selections 

Certain clients, often called managers, take on responsibility for managing shared resources. A 
client that manages a shared resource should take ownership of an appropriate selection, named 
using the conventions described in sections 1.2.3 and 1.2.6. A client that manages multiple 
shared resources (or groups of resources) should take ownership of a selection for each one. 

The manager may support conversion of various targets for that selection. Managers are encour- 
aged to use this technique as the primary means by which clients interact with the managed 
resource. Note that the conventions for interacting with the window manager predate this section; 
as a result many interactions with the window manager use other techniques. 

Before a manager takes ownership of a manager selection, it should use the GetSelectionOwner 
request to check whether the selection is already owned by another client, and, where appropriate, 
it should ask the user if the new manager should replace the old one. If so, it may then take own- 
ership of the selection. Managers should acquire the selection using a window created expressly 
for this purpose. Managers must conform to the rules for selection owners described in sections 
2.1 and 2.2, and they must also support the required targets listed in section 2.6.2. 

If a manager loses ownership of a manager selection, this means that a new manager is taking 
over its responsibilities. The old manager must release all resources it has managed and must 
then destroy the window that owned the selection. For example, a window manager losing own- 
ership of WM_S2 must deselect from SubstructureRedirect on the root window of screen 2 
before destroying the window that owned WM_S2. 

When the new manager notices that the window owning the selection has been destroyed, it 
knows that it can successfully proceed to control the resource it is planning to manage. If the old 
manager does not destroy the window within a reasonable time, the new manager should check 
with the user before destroying the window itself or killing the old manager. 

If a manager wants to give up, on its own, management of a shared resource controlled by a selec- 
tion, it must do so by releasing the resources it is managing and then by destroying the window 
that owns the selection. It should not first disown the selection, since this introduces a race condi- 
tion. 

Clients who are interested in knowing when the owner of a manager selection is no longer man- 
aging the corresponding shared resource should select for StructureNotify on the window own- 
ing the selection so they can be notified when the window is destroyed. Clients are warned that 
after doing a GetSelectionOwner and selecting for StructureNotify , they should do a GetSe- 
lectionOwner again to ensure that the owner did not change after initially getting the selection 
owner and before selecting for StructureNotify . 

Immediately after a manager successfully acquires ownership of a manager selection, it should 
announce its arrival by sending a ClientMessage event. This event should be sent using the 
SendEvent protocol request with the following arguments: 


Argument Value 


destination: the root window of screen 0, or the root window of the appropriate screen 

if the manager is managing a screen-specific resource 
propagate: False 

event-mask: StructureNotify 

event: ClientMessage 


type: 

MANAGER 

format: 

32 

data[0]: 10 

timestamp 

data[ 1] : 

manager selection atom 

data[2]: 

the window owning the selection 

data[3]: 

manager-selection-specific data 
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data[4]: manager-selection-specific data 


Clients that wish to know when a specific manager has started should select for StructureNotify 
on the appropriate root window and should watch for the appropriate MANAGER Client- 
Message . 

3. Peer-to-Peer Communication by Means of Cut Buffers 

The cut buffer mechanism is much simpler but much less powerful than the selection mechanism. 
The selection mechanism is active in that it provides a link between the owner and requestor 
clients. The cut buffer mechanism is passive; an owner places data in a cut buffer from which a 
requestor retrieves the data at some later time. 

The cut buffers consist of eight properties on the root of screen zero, named by the predefined 
atoms CUT_BUFFERO to CUT_BUFFER7. These properties must, at present, have type 
STRING and format 8. A client that uses the cut buffer mechanism must initially ensure that all 
eight properties exist by using ChangeProperty requests to append zero-length data to each. 

A client that stores data in the cut buffers (an owner) first must rotate the ring of buffers by plus 1 
by using RotateProperties requests to rename each buffer; that is, CUT_BUFFERO to 
CUT_BUFFER 1 , CUT_BUFFER1 to CUT_BUFFER2, ... , and CUT BUEFER7 to 
CUT_BUFFERO. It then must store the data into CUT_BUFFERO by using a ChangeProperty 
request in mode Replace . 

A client that obtains data from the cut buffers should use a GetProperty request to retrieve the 
contents of CUT_BUFFERO. 

In response to a specific user request, a client may rotate the cut buffers by minus 1 by using 
RotateProperties requests to rename each buffer; that is, CUT_BUFFER7 to CUT_BUFFER6, 
CUTJBUFFER6 to CUTJBUFFER5, . . . , and CUT_BUFFERO to CUT_BUFFER 7 . 

Data should be stored to the cut buffers and the ring rotated only when requested by explicit user 
action. Users depend on their mental model of cut buffer operation and need to be able to identify 
operations that transfer data to and fro. 

4. Client-to- Window-Manager Communication 

To permit window managers to perform their role of mediating the competing demands for 
resources such as screen space, the clients being managed must adhere to certain conventions and 
must expect the window managers to do likewise. These conventions are covered here from the 
client’s point of view. 

In general, these conventions are somewhat complex and will undoubtedly change as new win- 
dow management paradigms are developed. Thus, there is a strong bias toward defining only 
those conventions that are essential and that apply generally to all window management 
paradigms. Clients designed to run with a particular window manager can easily define private 
protocols to add to these conventions, but they must be aware that their users may decide to run 
some other window manager no matter how much the designers of the private protocol are con- 
vinced that they have seen the “one true light” of user interfaces. 

It is a principle of these conventions that a general client should neither know nor care which win- 
dow manager is running or, indeed, if one is running at all. The conventions do not support all 
client functions without a window manager running; for example, the concept of Iconic is not 
directly supported by clients. If no window manager is running, the concept of Iconic does not 
apply. A goal of the conventions is to make it possible to kill and restart window managers with- 
out loss of functionality. 


10 We use the notation data[n] to indicate the n* element of the LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the 
ClientMessage, according to the format field. The list is indexed from zero. 
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Each window manager will implement a particular window management policy; the choice of an 
appropriate window management policy for the user’s circumstances is not one for an individual 
client to make but will be made by the user or the user’s system administrator. This does not 
exclude the possibility of writing clients that use a private protocol to restrict themselves to oper- 
ating only under a specific window manager. Rather, it merely ensures that no claim of general 
utility is made for such programs. 

For example, the claim is often made: “The client I’m writing is important, and it needs to be on 
top.” Perhaps it is important when it is being run in earnest, and it should then be run under the 
control of a window manager that recognizes “important” windows through some private proto- 
col and ensures that they are on top. However, imagine, for example, that the “important” client 
is being debugged. Then, ensuring that it is always on top is no longer the appropriate window 
management policy, and it should be run under a window manager that allows other windows (for 
example, the debugger) to appear on top. 

4.1. Client’s Actions 

In general, the object of the X Version 1 1 design is that clients should, as far as possible, do 
exactly what they would do in the absence of a window manager, except for the following: 

• Hinting to the window manager about the resources they would like to obtain 

• Cooperating with the window manager by accepting the resources they are allocated even if 
they are not those requested 

• Being prepared for resource allocations to change at any time 

4.1.1. Creating a Top-Level Window 

A client’s top-level window is a window whose override-redirect attribute is False. It must either 
be a child of a root window, or it must have been a child of a root window immediately prior to 
having been reparented by the window manager. If the client reparents the window away from 
the root, the window is no longer a top-level window; but it can become a top-level window again 
if the client reparents it back to the root. 

A client usually would expect to create its top-level windows as children of one or more of the 
root windows by using some boilerplate like the following: 

win = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy), xsh.x, xsh.y, 

xsh. width, xsh.height, bw, bd, bg); 

If a particular one of the root windows was required, however, it could use something like the fol- 
lowing: 

win = XCreateSimpleWindow(dpy, RootWindow(dpy, screen), xsh.x, xsh.y, 

xsh. width, xsh.height, bw, bd, bg); 

Ideally, it should be possible to override the choice of a root window and allow clients (including 
window managers) to treat a nonroot window as a pseudo-root. This would allow, for example, 
the testing of window managers and the use of application-specific window managers to control 
the sub windows owned by the members of a related suite of clients. Doing so properly requires 
an extension, the design of which is under study. 

From the client’s point of view, the window manager will regard its top-level window as being in 
one of three states: 

• Normal 

• Iconic 

• Withdrawn 

Newly created windows start in the Withdrawn state. Transitions between states happen when the 
top-level window is mapped and unmapped and when the window manager receives certain 
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messages. For further details, see sections 4. 1.2.4 and 4.1.4. 

4.1.2. Client Properties 

Once the client has one or more top-level windows, it should place properties on those windows 
to inform the window manager of the behavior that the client desires. Window managers will 
assume values they find convenient for any of these properties that are not supplied; clients that 
depend on particular values must explicitly supply them. The window manager will not change 
properties written by the client. 

The window manager will examine the contents of these properties when the window makes the 
transition from the Withdrawn state and will monitor some properties for changes while the win- 
dow is in the Iconic or Normal state. When the client changes one of these properties, it must use 
Replace mode to overwrite the entire property with new data; the window manager will retain no 
memory of the old value of the property. All fields of the property must be set to suitable values 
in a single Replace mode ChangeProperty request. This ensures that the full contents of the 
property will be available to a new window manager if the existing one crashes, if it is shut down 
and restarted, or if the session needs to be shut down and restarted by the session manager. 

Convention 

Clients writing or rewriting window manager properties must ensure that the entire 
content of each property remains valid at all times. 

Some of these properties may contain the IDs of resources, such as windows or pixmaps. Clients 
should ensure that these resources exist for at least as long as the window on which the property 
resides. 

If these properties are longer than expected, clients should ignore the remainder of the property. 
Extending these properties is reserved to the X Consortium; private extensions to them are forbid- 
den. Private additional communication between clients and window managers should take place 
using separate properties. The only exception to this rule is the WM_PROTOCOLS property, 
which may be of arbitrary length and which may contain atoms representing private protocols 
(see section 4. 1.2.7). 

The next sections describe each of the properties the clients need to set, in turn. They are summa- 
rized in the table in section 4.4. 

4.I.2.I. WMLNAME Property 

The WM_NAME property is an uninterpreted string that the client wants the window manager to 
display in association with the window (for example, in a window headline bar). 

The encoding used for this string (and all other uninterpreted string properties) is implied by the 
type of the property. The type atoms to be used for this purpose are described in section 2.7.1. 

Window managers are expected to make an effort to display this information. Simply ignoring 
WM_NAME is not acceptable behavior. Clients can assume that at least the first part of this 
string is visible to the user and that if the information is not visible to the user, it is because the 
user has taken an explicit action to make it invisible. 

On the other hand, there is no guarantee that the user can see the WM_NAME string even if the 
window manager supports window headlines. The user may have placed the headline off-screen 
or have covered it by other windows. WM_NAME should not be used for application-critical 
information or to announce asynchronous changes of an application’s state that require timely 
user response. The expected uses are to permit the user to identify one of a number of instances 
of the same client and to provide the user with noncritical state information. 

Even window managers that support headline bars will place some limit on the length of the 
WM_NAME string that can be visible; brevity here will pay dividends. 
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4.1.2.2. WM_ICON_NAME Property 

The WM_ICON_NAME property is an uninterpreted string that the client wants to be displayed 
in association with the window when it is iconified (for example, in an icon label). In other 
respects, including the type, it is similar to WM_NAME. For obvious geometric reasons, fewer 
characters will normally be visible in WM_ICON_NAME than WM_NAME. 

Clients should not attempt to display this string in their icon pixmaps or windows; rather, they 
should rely on the window manager to do so. 

4.1.2.3. WM_NORMAL_HINTS Property 

The type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS. Its contents are as fol- 
lows: 


Field 

Type 

Comments 

flags 

CARD32 

(see the next table) 

pad 

4*CARD32 

For backwards compatibility 

min_width 

INT32 

If missing, assume base_width 

min_height 

INT32 

If missing, assume base_height 

max_width 

INT32 


max_height 

INT32 


width_inc 

INT32 


height_inc 

INT32 


min_aspect 

(INT32JNT32) 


max_aspect 

(INT32,INT32) 


base_width 

INT32 

If missing, assume min_width 

base_height 

INT32 

If missing, assume min_height 

win_gravity 

INT32 

If missing, assume NorthWest 


The WM_SIZE_HINTS. flags bit definitions are as follows: 


Name 

Value 

Field 

USPosition 

1 

User-specified x, y 

USSize 

2 

User-specified width, height 

PPosition 

4 

Program-specified position 

PSize 

8 

Program-specified size 

PMinSize 

16 

Program-specified minimum size 

PMaxSize 

32 

Program-specified maximum size 

PResizelnc 

64 

Program-specified resize increments 

PAspect 

128 

Program-specified min and max aspect ratios 

PBaseSize 

256 

Program-specified base size 

PWinGravity 

512 

Program-specified window gravity 


To indicate that the size and position of the window (when a transition from the Withdrawn state 
occurs) was specified by the user, the client should set the USPosition and USSize flags, which 
allow a window manager to know that the user specifically asked where the window should be 
placed or how the window should be sized and that further interaction is superfluous. To indicate 
that it was specified by the client without any user involvement, the client should set PPosition 
and PSize. 

The size specifiers refer to the width and height of the client’s window excluding borders. 
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The win_gravity may be any of the values specified for WENGRAVITY in the core protocol 
except for Unmap: Northwest (1), North (2), NorthEast (3), West (4), Center (5), East (6), 
SouthWest (7), South (8), and SouthEast (9). It specifies how and whether the client window 
wants to be shifted to make room for the window manager frame. 

If the win_gravity is Static, the window manager frame is positioned so that the inside border of 
the client window inside the frame is in the same position on the screen as it was when the client 
requested the transition from Withdrawn state. Other values of win_gravity specify a window ref- 
erence point. For NorthWest, NorthEast, SouthWest, and SouthEast the reference point is 
the specified outer comer of the window (on the outside border edge). For North, South, East, 
and West the reference point is the center of the specified outer edge of the window border. For 
Center the reference point is the center of the window. The reference point of the window man- 
ager frame is placed at the location on the screen where the reference point of the client window 
was when the client requested the transition from Withdrawn state. 

The min_width and min_height elements specify the minimum size that the window can be for 
the client to be useful. The max_width and max_height elements specify the maximum size. The 
base_width and base_height elements in conjunction with widthjnc and height_inc define an 
arithmetic progression of preferred window widths and heights for non-negative integers i and j: 

Osfont]I]ize]u’width R][eq] baseR]_width R][pl] R](i R][mu] widthR]_incR])Orfont] 
Osfont]I]ize]u’height R][eq] baseR]_height R] [pi] R](j R][mu] heightR]_incR])Orfont] 

Window managers are encouraged to use i and j instead of width and height in reporting window 
sizes to users. If a base size is not provided, the minimum size is to be used in its place and vice 
versa. 

The min_aspect and max_aspect fields are fractions with the numerator first and the denominator 
second, and they allow a client to specify the range of aspect ratios it prefers. Window managers 
that honor aspect ratios should take into account the base size in determining the preferred win- 
dow size. If a base size is provided along with the aspect ratio fields, the base size should be sub- 
tracted from the window size prior to checking that the aspect ratio falls in range. If a base size is 
not provided, nothing should be subtracted from the window size. (The minimum size is not to be 
used in place of the base size for this purpose.) 

4.I.2.4. WM_HINTS Property 

The WM_HINTS property (whose type is WM_HINTS) is used to communicate to the window 
manager. It conveys the information the window manager needs other than the window geometry, 
which is available from the window itself; the constraints on that geometry, which is available 
from the WM_NORMAL_HINTS structure; and various strings, which need separate properties, 
such as WM_NAME. The contents of the properties are as follows: 


Field 

Type 

Comments 

flags 

CARD32 

(see the next table) 

input 

CARD32 

The client’s input model 

initial_state 

CARD32 

The state when first mapped 

icon_pixmap 

PIXMAP 

The pixmap for the icon image 

icon_window 

WINDOW 

The window for the icon image 

icon_x 

INT32 

The icon location 

icon_y 

INT32 


icon_mask 

PIXMAP 

The mask for the icon shape 

window_group 

WINDOW 

The ID of the group leader window 
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The WM_HINTS. flags bit definitions are as follows: 


Name 

Value 

Field 

InputHint 

1 

input 

StateHint 

2 

initial_state 

IconPixmapHint 

4 

icon_pixmap 

IconWindowHint 

8 

icon_window 

IconPositionHint 

16 

icon_x & icon_y 

IconMaskHint 

32 

icon_mask 

WindowGroupHint 

64 

window_group 

MessageHint 

128 

(this bit is obsolete) 

Urgency Hint 

256 

urgency 


Window managers are free to assume convenient values for all fields of the WM_HINTS property 
if a window is mapped without one. 

The input field is used to communicate to the window manager the input focus model used by the 
client (see section 4.1.7). 

Clients with the Globally Active and No Input models should set the input flag to False . Clients 
with the Passive and Locally Active models should set the input flag to True . 

From the client’s point of view, the window manager will regard the client’s top-level window as 
being in one of three states: 

• Normal 

• Iconic 

• Withdrawn 

The semantics of these states are described in section 4.1.4. Newly created windows start in the 
Withdrawn state. Transitions between states happen when a top-level window is mapped and 
unmapped and when the window manager receives certain messages. 

The value of the initial_state field determines the state the client wishes to be in at the time the 
top-level window is mapped from the Withdrawn state, as shown in the following table: 

State Value Comments 

NormalState 1 The window is visible. 

IconicState 3 The icon is visible. 

The icon_pixmap field may specify a pixmap to be used as an icon. This pixmap should be: 

• One of the sizes specified in the WM_ICON_SIZE property on the root if it exists (see sec- 
tion 4. 1.3.2). 

• 1-bit deep. The window manager will select, through the defaults database, suitable back- 
ground (for the 0 bits) and foreground (for the 1 bits) colors. These defaults can, of course, 
specify different colors for the icons of different clients. 

The icon_mask specifies which pixels of the icon_pixmap should be used as the icon, allowing 
for icons to appear nonrectangular. 

The icon_window field is the ID of a window the client wants used as its icon. Most, but not all, 
window managers will support icon windows. Those that do not are likely to have a user inter- 
face in which small windows that behave like icons are completely inappropriate. Clients should 
not attempt to remedy the omission by working around it. 
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Clients that need more capabilities from the icons than a simple 2-color bitmap should use icon 
windows. Rules for clients that do are set out in section 4.1.9. 

The (icon_x,icon_y) coordinate is a hint to the window manager as to where it should position the 
icon. The policies of the window manager control the positioning of icons, so clients should not 
depend on attention being paid to this hint. 

The window_group field lets the client specify that this window belongs to a group of windows. 
An example is a single client manipulating multiple children of the root window. 

Conventions 

1 . The window_group field should be set to the ID of the group leader. The window 
group leader may be a window that exists only for that purpose; a placeholder group 
leader of this kind would never be mapped either by the client or by the window 
manager. 

2. The properties of the window group leader are those for the group as a whole (for 
example, the icon to be shown when the entire group is iconified). 

Window managers may provide facilities for manipulating the group as a whole. Clients, at pre- 
sent, have no way to operate on the group as a whole. 

The messages bit, if set in the flags field, indicates that the client is using an obsolete window 
manager communication protocol, 11 rather than the WM_PROTOCOLS mechanism of section 
4. 1.2.7. 

The UrgencyHint flag, if set in the flags field, indicates that the client deems the window con- 
tents to be urgent, requiring the timely response of the user. The window manager must make 
some effort to draw the user’s attention to this window while this flag is set. The window man- 
ager must also monitor the state of this flag for the entire time the window is in the Normal or 
Iconic state and must take appropriate action when the state of the flag changes. The flag is other- 
wise independent of the window’s state; in particular, the window manager is not required to 
deiconify the window if the client sets the flag on an Iconic window. Clients must provide some 
means by which the user can cause the UrgencyHint flag to be set to zero or the window to be 
withdrawn. The user’s action can either mitigate the actual condition that made the window 
urgent, or it can merely shut off the alarm. 

Rationale 

This mechanism is useful for alarm dialog boxes or reminder windows, in cases 
where mapping the window is not enough (e.g., in the presence of multi-workspace 
or virtual desktop window managers), and where using an override-redirect window 
is too intrusive. For example, the window manager may attract attention to an urgent 
window by adding an indicator to its title bar or its icon. Window managers may also 
take additional action for a window that is newly urgent, such as by flashing its icon 
(if the window is iconic) or by raising it to the top of the stack. 

4.I.2.5. WM_CLASS Property 

The WM_CLASS property (of type STRING without control characters) contains two consecu- 
tive null-terminated strings. These specify the Instance and Class names to be used by both the 
client and the window manager for looking up resources for the application or as identifying 
information. This property must be present when the window leaves the Withdrawn state and 
may be changed only while the window is in the Withdrawn state. Window managers may 

11 This obsolete protocol was described in the July 27, 1988, draft of the ICCCM. Windows using it can also be detected because their 
WM_HINTS properties are 4 bytes longer than expected. Window managers are free to support clients using the obsolete protocol in a back- 
wards compatibility mode. 
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examine the property only when they start up and when the window leaves the Withdrawn state, 
but there should be no need for a client to change its state dynamically. 

The two strings, respectively, are: 

• A string that names the particular instance of the application to which the client that owns 
this window belongs. Resources that are specified by instance name override any resources 
that are specified by class name. Instance names can be specified by the user in an operat- 
ing-system specific manner. On POSIX-conformant systems, the following conventions are 
used: 

- If “-name NAME” is given on the command line, NAME is used as the instance 
name. 

- Otherwise, if the environment variable RESOURCE_NAME is set, its value will be 
used as the instance name. 

- Otherwise, the trailing part of the name used to invoke the program (argv[0] stripped 
of any directory names) is used as the instance name. 

• A string that names the general class of applications to which the client that owns this win- 
dow belongs. Resources that are specified by class apply to all applications that have the 
same class name. Class names are specified by the application writer. Examples of com- 
monly used class names include: “Emacs”, “XTerm”, “XClock”, “XLoad”, and so on. 

Note that WM_CLASS strings are null-terminated and, thus, differ from the general conventions 
that STRING properties are null-separated. This inconsistency is necessary for backwards com- 
patibility. 

4.1.2.6. WM_TRANSIENT_FOR Property 

The WM_TRANSIENT_FOR property (of type WINDOW) contains the ID of another top-level 
window. The implication is that this window is a pop-up on behalf of the named window, and 
window managers may decide not to decorate transient windows or may treat them differently in 
other ways. In particular, window managers should present newly mapped WM_TRAN- 
SIENT_FOR windows without requiring any user interaction, even if mapping top-level windows 
normally does require interaction. Dialogue boxes, for example, are an example of windows that 
should have WM_TR AN SIENT_FOR set. 

It is important not to confuse WM_TRANSIENT_FOR with override-redirect. WM_TRAN- 
SIENT_FOR should be used in those cases where the pointer is not grabbed while the window is 
mapped (in other words, if other windows are allowed to be active while the transient is up). If 
other windows must be prevented from processing input (for example, when implementing pop- 
up menus), use override-redirect and grab the pointer while the window is mapped. 

4.1.2.7. WM_PROTO COLS Property 

The WM_PROTOCOLS property (of type ATOM) is a list of atoms. Each atom identifies a com- 
munication protocol between the client and the window manager in which the client is willing to 
participate. Atoms can identify both standard protocols and private protocols specific to individ- 
ual window managers. 

All the protocols in which a client can volunteer to take part involve the window manager sending 
the client a ClientMessage event and the client taking appropriate action. For details of the con- 
tents of the event, see section 4.2.8. In each case, the protocol transactions are initiated by the 
window manager. 

The WM_PROTOCOLS property is not required. If it is not present, the client does not want to 
participate in any window manager protocols. 

The X Consortium will maintain a registry of protocols to avoid collisions in the name space. 

The following table lists the protocols that have been defined to date. 
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Protocol 


Section Purpose 


WM_TAKE_FOCUS 4.1.7 

WM_SAVE_YOURSELF Appendix C 
WM_DELETE_WINDOW 4.2.8. 1 


Assignment of input focus 

Save client state request (deprecated) 

Request to delete top-level window 


It is expected that this table will grow over time. 


4.I.2.8. WM_COLORMAP_WINDOWS Property 

The WM_COLORMAP_WINDOWS property (of type WINDOW) on a top-level window is a 
list of the IDs of windows that may need colormaps installed that differ from the colormap of the 
top-level window. The window manager will watch this list of windows for changes in their col- 
ormap attributes. The top-level window is always (implicitly or explicitly) on the watch list. For 
the details of this mechanism, see section 4.1.8. 


4.I.2.9. WM_CLIENT_MACHINE Property 

The client should set the WM_CLIENT_MACHINE property (of one of the TEXT types) to a 
string that forms the name of the machine running the client as seen from the machine running the 
server. 

4.1.3. Window Manager Properties 

The properties that were described in the previous section are those that the client is responsible 
for maintaining on its top-level windows. This section describes the properties that the window 
manager places on client’s top-level windows and on the root. 

4.I.3.I. WM_STATE Property 

The window manager will place a WM_STATE property (of type WM_STATE) on each top-level 
client window that is not in the Withdrawn state. Top-level windows in the Withdrawn state may 
or may not have the WM_STATE property. Once the top-level window has been withdrawn, the 
client may re-use it for another purpose. Clients that do so should remove the WM_STATE prop- 
erty if it is still present. 

Some clients (such as xprop) will ask the user to click over a window on which the program is to 
operate. Typically, the intent is for this to be a top-level window. To find a top-level window, 
clients should search the window hierarchy beneath the selected location for a window with the 
WM_STATE property. This search must be recursive in order to cover all window manager 
reparenting possibilities. If no window with a WM_STATE property is found, it is recommended 
that programs use a mapped child-of-root window if one is present beneath the selected location. 

The contents of the WM_STATE property are defined as follows: 

Field Tipe Comments 

state CARD32 (see the next table) 

icon WINDOW ID of icon window 

The following table lists the WM_STATE. state values: 
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State Value 


WithdrawnState 0 

NormalState 1 

IconicState 3 


Adding other fields to this property is reserved to the X Consortium. Values for the state field 
other than those defined in the above table are reserved for use by the X Consortium. 

The state field describes the window manager’s idea of the state the window is in, which may not 
match the client’s idea as expressed in the initial_state field of the WMJHINTS property (for 
example, if the user has asked the window manager to iconify the window). If it is NormalState , 
the window manager believes the client should be animating its window. If it is IconicState, the 
client should animate its icon window. In either state, clients should be prepared to handle expo- 
sure events from either window. 

When the window is withdrawn, the window manager will either change the state field’s value to 
WithdrawnState or it will remove the WM_STATE property entirely. 

The icon field should contain the window ID of the window that the window manager uses as the 
icon for the window on which this property is set. If no such window exists, the icon field should 
be None. Note that this window could be but is not necessarily the same window as the icon 
window that the client may have specified in its WMJHINTS property. The WM_STATE icon 
may be a window that the window manager has supplied and that contains the client’s icon 
pixmap, or it may be an ancestor of the client’s icon window. 

4.I.3.2. WM_ICON_SIZE Property 

A window manager that wishes to place constraints on the sizes of icon pixmaps and/or windows 
should place a property called WM_ICON_SIZE on the root. The contents of this property are 
listed in the following table. 


Field 

Type 

Comments 

min_width 

CARD32 

The data for the icon size series 

min_height 

CARD32 


max_width 

CARD32 


max_height 

CARD32 


width_inc 

CARD32 


height_inc 

CARD32 



For more details see section 14. 1. 12 in Xlib - C Language X Interface. 

4.1.4. Changing Window State 

From the client’s point of view, the window manager will regard each of the client’s top-level 

windows as being in one of three states, whose semantics are as follows: 

• NormalState - The client’s top-level window is viewable. 

• IconicState - The client’s top-level window is iconic (whatever that means for this window 
manager). The client can assume that its top-level window is not viewable, its icon_window 
(if any) will be viewable and, failing that, its icon_pixmap (if any) or its WM_ICON_NAME 
will be displayed. 

• WithdrawnState - Neither the client’s top-level window nor its icon is visible. 

In fact, the window manager may implement states with semantics other than those described 

above. For example, a window manager might implement a concept of an “inactive” state in 
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which an infrequently used client’s window would be represented as a string in a menu. But this 
state is invisible to the client, which would see itself merely as being in the Iconic state. 

Newly created top-level windows are in the Withdrawn state. Once the window has been pro- 
vided with suitable properties, the client is free to change its state as follows: 

• Withdrawn — > Normal - The client should map the window with WM_HINTS.initial_state 
being NormalState. 

• Withdrawn — > Iconic - The client should map the window with WM_HINTS.initial_state 
being IconicState. 

• Normal — » Iconic - The client should send a ClientMessage event as described later in this 
section. 

• Normal — » Withdrawn - The client should unmap the window and follow it with a synthetic 
UnmapNotify event as described later in this section. 

• Iconic — » Normal - The client should map the window. The contents ofWM_HINTS.ini- 
tial_state are irrelevant in this case. 

• Iconic — > Withdrawn - The client should unmap the window and follow it with a synthetic 
UnmapNotify event as described later in this section. 

Only the client can effect a transition into or out of the Withdrawn state. Once a client’s window 
has left the Withdrawn state, the window will be mapped if it is in the Normal state and the win- 
dow will be unmapped if it is in the Iconic state. Reparenting window managers must unmap the 
client’s window when it is in the Iconic state, even if an ancestor window being unmapped ren- 
ders the client’s window unviewable. Conversely, if a reparenting window manager renders the 
client’s window unviewable by unmapping an ancestor, the client’s window is by definition in the 
Iconic state and must also be unmapped. 

Advice to Implementors 

Clients can select for StructureNotify on their top-level windows to track transitions 
between Normal and Iconic states. Receipt of a MapNotify event will indicate a 
transition to the Normal state, and receipt of an UnmapNotify event will indicate a 
transition to the Iconic state. 

When changing the state of the window to Withdrawn, the client must (in addition to unmapping 
the window) send a synthetic UnmapNotify event by using a SendEvent request with the fol- 
lowing arguments: 


Argument 


Value 


destination: 

propagate: 

event-mask: 

event: an UnmapNotify with: 
event: 
window: 
from-configure: 


The root 
False 

( SubstructureRedirect|SubstructureNotify ) 

The root 

The window itself 
False 
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Rationale 

The reason for requiring the client to send a synthetic UnmapNotify event is to 
ensure that the window manager gets some notification of the client’s desire to 
change state, even though the window may already be unmapped when the desire is 
expressed. 

Advice to Implementors 

For compatibility with obsolete clients, window managers should trigger the transi- 
tion to the Withdrawn state on the real UnmapNotify rather than waiting for the syn- 
thetic one. They should also trigger the transition if they receive a synthetic Unmap- 
Notify on a window for which they have not yet received a real UnmapNotify . 

When a client withdraws a window, the window manager will then update or remove the 
WM_STATE property as described in section 4. 1.3.1. Clients that want to re-use a client window 
(e.g., by mapping it again or reparenting it elsewhere) after withdrawing it must wait for the with- 
drawal to be complete before proceeding. The preferred method for doing this is for clients to 
wait for the window manager to update or remove the WM_STATE property. 12 

If the transition is from the Normal to the Iconic state, the client should send a ClientMessage 
event to the root with: 

• Window == the window to be iconified 

• Type 13 == the atom WM_CHAN GE_STATE 

• Format == 32 

• Data[0] == IconicState 


Rationale 

The format of this ClientMessage event does not match the format of 
ClientMessages in section 4.2.8. This is because they are sent by the window 
manager to clients, and this message is sent by clients to the window manager. 

Other values of data[0] are reserved for future extensions to these conventions. The parameters of 
the SendEvent request should be those described for the synthetic UnmapNotify event. 

Advice to Implementors 

Clients can also select for VisibilityChange events on their top-level or icon win- 
dows. They will then receive a VisibilityNotify(state==FullyObscured) event when 
the window concerned becomes completely obscured even though mapped (and thus, 
perhaps a waste of time to update) and a VisibilityNotify (state !=FullyObscured) 
event when it becomes even partly viewable. 


12 Earlier versions of these conventions prohibited clients from reading the WM_STATE property. Clients operating under the earlier 
conventions used the technique of tracking ReparentNotify events to wait for the top-level window to be reparented back to the root win- 
dow. This is still a valid technique; however, it works only for reparenting window managers, and the WM_STATE technique is to be pre- 
ferred. 

13 The type field of the ClientMessage event (called the message_type field by Xlib) should not be confused with the code field of the 
event itself, which will have the value 33 (ClientMessage). 


30 



Inter- Client Communication Conventions 


XI 1, Release 6.4 


Advice to Implementors 

When a window makes a transition from the Normal state to either the Iconic or the 
Withdrawn state, clients should be aware that the window manager may make tran- 
sients for this window inaccessible. Clients should not rely on transient windows 
being available to the user when the transient owner window is not in the Normal 
state. When withdrawing a window, clients are advised to withdraw transients for the 
window. 


4.1.5. Configuring the Window 

Clients can resize and reposition their top-level windows by using the Configure Window 
request. The attributes of the window that can be altered with this request are as follows: 

• The [x,y] location of the window’s upper left-outer comer 

• The [width, height] of the inner region of the window (excluding borders) 

• The border width of the window 

• The window’s position in the stack 

The coordinate system in which the location is expressed is that of the root (irrespective of any 
reparenting that may have occurred). The border width to be used and win_gravity position hint 
to be used are those most recently requested by the client. Client configure requests are inter- 
preted by the window manager in the same manner as the initial window geometry mapped from 
the Withdrawn state, as described in section 4. 1.2.3. Clients must be aware that there is no guar- 
antee that the window manager will allocate them the requested size or location and must be pre- 
pared to deal with any size and location. If the window manager decides to respond to a Config- 
ureRequest request by: 

• Not changing the size, location, border width, or stacking order of the window at all. 

A client will receive a synthetic ConfigureNotify event that describes the (unchanged) 
geometry of the window. The (x,y) coordinates will be in the root coordinate system, 
adjusted for the border width the client requested, irrespective of any reparenting that has 
taken place. The border_width will be the border width the client requested. The client will 
not receive a real ConfigureNotify event because no change has actually taken place. 

• Moving or restacking the window without resizing it or changing its border width. 

A client will receive a synthetic ConfigureNotify event following the change that describes 
the new geometry of the window. The event’s (x,y) coordinates will be in the root coordi- 
nate system adjusted for the border width the client requested. The border_width will be the 
border width the client requested. The client may not receive a real ConfigureNotify event 
that describes this change because the window manager may have reparented the top-level 
window. If the client does receive a real event, the synthetic event will follow the real one. 

• Resizing the window or changing its border width (regardless of whether the window was 
also moved or restacked). 

A client that has selected for StructureNotify events will receive a real ConfigureNotify 
event. Note that the coordinates in this event are relative to the parent, which may not be the 
root if the window has been reparented. The coordinates will reflect the actual border width 
of the window (which the window manager may have changed). The Translate- 
Coordinates request can be used to convert the coordinates if required. 

The general rule is that coordinates in real ConfigureNotify events are in the parent’s space; in 
synthetic events, they are in the root space. 
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Advice to Implementors 

Clients cannot distinguish between the case where a top-level window is resized and 
moved from the case where the window is resized but not moved, since a real Con- 
figureNotify event will be received in both cases. Clients that are concerned with 
keeping track of the absolute position of a top-level window should keep a piece of 
state indicating whether they are certain of its position. Upon receipt of a real Con- 
figureNotify event on the top-level window, the client should note that the position is 
unknown. Upon receipt of a synthetic ConfigureNotify event, the client should note 
the position as known, using the position in this event. If the client receives a 
KeyPress, Key Release, ButtonPress, ButtonRelease, MotionNotify, 

EnterNotify , or LeaveNotify event on the window (or on any descendant), the 
client can deduce the top-level window’s position from the difference between the 
(event-x, event-y) and (root-x, root-y) coordinates in these events. Only when the 
position is unknown does the client need to use the TranslateCoordinates request to 
find the position of a top-level window. 

Clients should be aware that their borders may not be visible. Window managers are free to use 
reparenting techniques to decorate client’s top-level windows with borders containing titles, con- 
trols, and other details to maintain a consistent look-and-feel. If they do, they are likely to over- 
ride the client’s attempts to set the border width and set it to zero. Clients, therefore, should not 
depend on the top-level window’s border being visible or use it to display any critical informa- 
tion. Other window managers will allow the top-level windows border to be visible. 

Convention 

Clients should set the desired value of the border-width attribute on all Config- 
ure Window requests to avoid a race condition. 

Clients that change their position in the stack must be aware that they may have been reparented, 
which means that windows that used to be siblings no longer are. Using a nonsibling as the sib- 
ling parameter on a Configure Window request will cause an error. 

Convention 

Clients that use a Configure Window request to request a change in their position in 
the stack should do so using None in the sibling field. 

Clients that must position themselves in the stack relative to some window that was originally a 
sibling must do the ConfigureWindow request (in case they are running under a nonreparenting 
window manager), be prepared to deal with a resulting error, and then follow with a synthetic 
ConfigureRequest event by invoking a SendEvent request with the following arguments: 


Argument 


Value 


destination: 

propagate: 

event-mask: 

event: a ConfigureRequest 
with: 

event: 

window: 


The root 
False 

(SubstructureRedirect|SubstructureNotify) 


The root 

The window itself 

Other parameters from the ConfigureWindow request 
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Window managers are in any case free to position windows in the stack as they see fit, and so 
clients should not rely on receiving the stacking order they have requested. Clients should ignore 
the above-sibling field of both real and synthetic ConfigureNotify events received on their top- 
level windows because this field may not contain useful information. 

4.1.6. Changing Window Attributes 

The attributes that may be supplied when a window is created may be changed by using the 
ChangeWindowAttributes request. The window attributes are listed in the following table: 


Attribute Private to CUent 


Background pixmap Yes 

Background pixel Yes 

Border pixmap Yes 

Border pixel Yes 

Bit gravity Yes 

Window gravity No 

Backing-store hint Yes 

Save-under hint No 

Event mask No 

Do-not-propagate mask Yes 

Override-redirect flag No 

Colormap Yes 

Cursor Yes 


Most attributes are private to the client and will never be interfered with by the window manager. 

For the attributes that are not private to the client: 

• The window manager is free to override the window gravity; a reparenting window manager 
may want to set the top-level window’s window gravity for its own purposes. 

• Clients are free to set the save-under hint on their top-level windows, but they must be aware 
that the hint may be overridden by the window manager. 

• Windows, in effect, have per-client event masks, and so, clients may select for whatever 
events are convenient irrespective of any events the window manager is selecting for. There 
are some events for which only one client at a time may select, but the window manager 
should not select for them on any of the client’s windows. 

• Clients can set override-redirect on top-level windows but are encouraged not to do so except 
as described in sections 4.1.10 and 4.2.9. 

4.1.7. Input Focus 

There are four models of input handling: 

• No Input - The client never expects keyboard input. An example would be xload or another 
output-only client. 

• Passive Input - The client expects keyboard input but never explicitly sets the input focus. 

An example would be a simple client with no subwindows, which will accept input in Point- 
erRoot mode or when the window manager sets the input focus to its top-level window (in 
click- to-type mode). 

• Locally Active Input - The client expects keyboard input and explicitly sets the input focus, 
but it only does so when one of its windows already has the focus. An example would be a 
client with subwindows defining various data entry fields that uses Next and Prev keys to 
move the input focus between the fields. It does so when its top-level window has acquired 
the focus in PointerRoot mode or when the window manager sets the input focus to its top- 
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level window (in click-to-type mode). 

• Globally Active Input - The client expects keyboard input and explicitly sets the input focus, 
even when it is in windows the client does not own. An example would be a client with a 
scroll bar that wants to allow users to scroll the window without disturbing the input focus 
even if it is in some other window. It wants to acquire the input focus when the user clicks in 
the scrolled region but not when the user clicks in the scroll bar itself. Thus, it wants to pre- 
vent the window manager from setting the input focus to any of its windows. 

The four input models and the corresponding values of the input field and the presence or absence 
of the WM_TAKE_FOCUS atom in the WM_PROTOCOLS property are listed in the following 
table: 


Input Model Input Field WM_TAKE_FOCUS 


No Input 

False 

Passive 

True 

Locally Active 

True 

Globally Active 

False 


Absent 

Absent 

Present 

Present 


Passive and Locally Active clients set the input field of WM_HINTS to True, which indicates 
that they require window manager assistance in acquiring the input focus. No Input and Globally 
Active clients set the input field to False, which requests that the window manager not set the 
input focus to their top-level window. 

Clients that use a SetlnputFocus request must set the time field to the timestamp of the event 
that caused them to make the attempt. This cannot be a Focusln event because they do not have 
timestamps. Clients may also acquire the focus without a corresponding EnterNotify. Note that 
clients must not use CurrentTime in the time field. 

Clients using the Globally Active model can only use a SetlnputFocus request to acquire the 
input focus when they do not already have it on receipt of one of the following events: 

• ButtonPress 

• ButtonRelease 

• Passive-grabbed KeyPress 

• Passive-grabbed KeyRelease 

In general, clients should avoid using passive-grabbed key events for this purpose, except when 
they are unavoidable (as, for example, a selection tool that establishes a passive grab on the keys 
that cut, copy, or paste). 

The method by which the user commands the window manager to set the focus to a window is up 
to the window manager. For example, clients cannot determine whether they will see the click 
that transfers the focus. 

Windows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property may receive a 
ClientMessage event from the window manager (as described in section 4.2.8) with 
WM_TAKE_FOCUS in its data[0] field and a valid timestamp (i.e., not CurrentTime) in its 
data[l] field. If they want the focus, they should respond with a SetlnputFocus request with its 
window field set to the window of theirs that last had the input focus or to their default input win- 
dow, and the time field set to the timestamp in the message. For further information, see section 
4.2.7. 

A client could receive WM_TAKE_FOCUS when opening from an icon or when the user has 
clicked outside the top-level window in an area that indicates to the window manager that it 
should assign the focus (for example, clicking in the headline bar can be used to assign the focus). 

The goal is to support window managers that want to assign the input focus to a top-level window 
in such a way that the top-level window either can assign it to one of its subwindows or can 
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decline the offer of the focus. For example, a clock or a text editor with no currently open frames 
might not want to take focus even though the window manager generally believes that clients 
should take the input focus after being deiconified or raised. 

Clients that set the input focus need to decide a value for the revert-to field of the SetlnputFocus 
request. This determines the behavior of the input focus if the window the focus has been set to 
becomes not viewable. The value can be any of the following: 

• Parent - In general, clients should use this value when assigning focus to one of their sub- 
windows. Unmapping the subwindow will cause focus to revert to the parent, which is prob- 
ably what you want. 

• PointerRoot - Using this value with a click-to-type focus management policy leads to race 
conditions because the window becoming unviewable may coincide with the window man- 
ager deciding to move the focus elsewhere. 

• None - Using this value causes problems if the window manager reparents the window, as 
most window managers will, and then crashes. The input focus will be None, and there will 
probably be no way to change it. 

Note that neither PointerRoot nor None is really safe to use. 

Convention 

Clients that invoke a SetlnputFocus request should set the revert-to argument to 

Parent. 

A convention is also required for clients that want to give up the input focus. There is no safe 
value set for them to set the input focus to; therefore, they should ignore input material. 

Convention 

Clients should not give up the input focus of their own volition. They should ignore 

input that they receive instead. 


4.1.8. Colormaps 

The window manager is responsible for installing and uninstalling colormaps on behalf of clients 
with top-level windows that the window manager manages. 

Clients provide the window manager with hints as to which colormaps to install and uninstall. 
Clients must not install or uninstall colormaps themselves (except under the circumstances noted 
below). When a client’s top-level window gets the colormap focus (as a result of whatever col- 
ormap focus policy is implemented by the window manager), the window manager will ensure 
that one or more of the client’s colormaps are installed. 

Clients whose top-level windows and subwindows all use the same colormap should set its ID in 
the colormap field of the top-level window’s attributes. They should not set a WM_COL- 
ORMAP_WINDOWS property on the top-level window. If they want to change the colormap, 
they should change the top-level window’s colormap attribute. The window manager will track 
changes to the window’s colormap attribute and install colormaps as appropriate. 

Clients that create windows can use the value CopyFromParent to inherit their parent’s col- 
ormap. Window managers will ensure that the root window’s colormap field contains a colormap 
that is suitable for clients to inherit. In particular, the colormap will provide distinguishable col- 
ors for BlackPixel and WhitePixel . 

Top-level windows that have subwindows or override-redirect pop-up windows whose colormap 
requirements differ from the top-level window should have a WM_COLORMAP_WINDOWS 
property. This property contains a list of IDs for windows whose colormaps the window manager 
should attempt to have installed when, in the course of its individual colormap focus policy, it 
assigns the colormap focus to the top-level window (see section 4. 1.2.8). The list is ordered by 
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the importance to the client of having the colormaps installed. The window manager will track 
changes to this property and will track changes to the colormap attribute of the windows in the 
property. 

If the relative importance of colormaps changes, the client should update the WM_COL- 
ORMAP_WINDOWS property to reflect the new ordering. If the top-level window does not 
appear in the list, the window manager will assume it to be of higher priority than any window in 
the list. 

WM_TRANSIENT_FOR windows can either have their own WM_COLORMAP_WINDOWS 
property or appear in the property of the window they are transient for, as appropriate. 

Rationale 

An alternative design was considered for how clients should hint to the window man- 
ager about their colormap requirements. This alternative design specified a list of 
colormaps instead of a list of windows. The current design, a list of windows, was 
chosen for two reasons. First, it allows window managers to find the visuals of the 
colormaps, thus permitting visual-dependent colormap installation policies. Second, 
it allows window managers to select for VisibilityChange events on the windows 
concerned and to ensure that colormaps are only installed if the windows that need 
them are visible. The alternative design allows for neither of these policies. 


Advice to Implementors 

Clients should be aware of the min-installed-maps and max-installed-maps fields of 
the connection setup information, and the effect that the mi nimum value has on the 
“required list” defined by the Protocol in the description of the InstallColormap 
request. Briefly, the min-installed-maps most recently installed maps are guaranteed 
to be installed. This value is often one; clients needing multiple colormaps should 
beware. 


Whenever possible, clients should use the mechanisms described above and let the window man- 
ager handle colormap installation. However, clients are permitted to perform colormap installa- 
tion on their own while they have the pointer grabbed. A client performing colormap installation 
must notify the window manager prior to the first installation. When the client has finished its 
colormap installation, it must also notify the window manager. The client notifies the window 
manager by issuing a SendEvent request with the following arguments: 


Argument Value 


destination: 

propagate: 

event-mask: 

event: a ClientMessage with: 
window: 
type: 
format: 
data[0] : 

data[l]: 

data[2]: 

data[3]: 


the root window of the screen on which the colormap is 
being installed 

False 

ColormapChange 

the root window, as above 

WM_COLORMAP_NOTIFY 

32 

the timestamp of the event that caused the client to start 
or stop installing colormaps 

1 if the client is starting colormap installation, 0 if the 
client is finished with colormap installation 
reserved, must be zero 
reserved, must be zero 
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data [4]: 


reserved, must be zero 


This feature was introduced in version 2.0 of this document, and there will be a significant period 
of time before all window managers can be expected to implement this feature. Before using this 
feature, clients must check the compliance level of the window manager (using the mechanism 
described in section 4.3) to verify that it supports this feature. This is necessary to prevent col- 
ormap installation conflicts between clients and older window managers. 

Window managers should refrain from installing colormaps while a client has requested control 
of colormap installation. The window manager should continue to track the set of installed col- 
ormaps so that it can reinstate its colormap focus policy when the client has finished colormap 
installation. 

This technique has race conditions that may result in the colormaps continuing to be installed 
even after a client has issued its notification message. For example, the window manager may 
have issued some InstallColormap requests that are not executed until after the client’s SendE- 
vent and InstallColormap requests, thus uninstalling the client’s colormaps. If this occurs while 
the client still has the pointer grabbed and before the client has issued the “finished” message, the 
client may reinstall the desired colormaps. 

Advice to Implementors 

Clients are expected to use this mechanism for things such as pop-up windows and 
for animations that use override-redirect windows. 

If a client fails to issue the “finished” message, the window manager may be left in a 
state where its colormap installation policy is suspended. Window manager imple- 
mentors may want to implement a feature that resets colormap installation policy in 
response to a command from the user. 


4.1.9. Icons 

A client can hint to the window manager about the desired appearance of its icon by setting: 

• A string in WM_ICON_NAME. 

All clients should do this because it provides a fallback for window managers whose ideas 
about icons differ widely from those of the client. 

• A Pixmap into the icon_pixmap field of the WM_HINTS property and possibly another into 
the icon_mask field. 

The window manager is expected to display the pixmap masked by the mask. The pixmap 
should be one of the sizes found in the WM_ICON_SIZE property on the root. If this prop- 
erty is not found, the window manager is unlikely to display icon pixmaps. Window man- 
agers usually will clip or tile pixmaps that do not match WM_ICON_SIZE. 

• A window into the icon_window field of the WM_HINTS property. 

The window manager is expected to map that window whenever the client is in the Iconic 
state. In general, the size of the icon window should be one of those specified in 
WM_ICON_SIZE on the root, if it exists. Window managers are free to resize icon win- 
dows. 

In the Iconic state, the window manager usually will ensure that: 

• If the window’s WM_HINTS.icon_window is set, the window it names is visible. 

• If the window’s WM_HINTS.icon_window is not set but the window’s 
WM_HINTS.icon_pixmap is set, the pixmap it names is visible. 

• Otherwise, the window’s WM_ICON_NAME string is visible. 
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Clients should observe the following conventions about their icon windows: 

Conventions 

1. The icon window should be an InputOutput child of the root. 

2. The icon window should be one of the sizes specified in the WM_ICON_SIZE prop- 
erty on the root. 

3. The icon window should use the root visual and default colormap for the screen in 
question. 

4. Clients should not map their icon windows. 

5. Clients should not unmap their icon windows. 

6. Clients should not configure their icon windows. 

7. Clients should not set override-redirect on their icon windows or select for Resize- 
Redirect events on them. 

8. Clients must not depend on being able to receive input events by means of their icon 
windows. 

9. Clients must not manipulate the borders of their icon windows. 

10. Clients must select for Exposure events on their icon window and repaint it when 
requested. 

Window managers will differ as to whether they support input events to client’s icon windows; 

most will allow the client to receive some subset of the keys and buttons. 

Window managers will ignore any WM_NAME, WM_ICON_NAME, WM_NORMAL_fflNTS, 

WMJHINTS, WM_CLASS, WM_TRANSIENT_FOR, WM_PROTOCOLS, WM_COL- 

ORM AP_WINDOW S , WM_COMMAND, or WM_CLIENT_MACfflNE properties they find on 

icon windows. 

4.1.10. Pop-up Windows 

Clients that wish to pop up a window can do one of three things: 

1. They can create and map another normal top-level window, which will get decorated and 
managed as normal by the window manager. See the discussion of window groups that fol- 
lows. 

2. If the window will be visible for a relatively short time and deserves a somewhat lighter 
treatment, they can set the WM_TRANSIENT_FOR property. They can expect less deco- 
ration but can set all the normal window manager properties on the window. An example 
would be a dialog box. 

3. If the window will be visible for a very short time and should not be decorated at all, the 
client can set override-redirect on the window. In general, this should be done only if the 
pointer is grabbed while the window is mapped. The window manager will never interfere 
with these windows, which should be used with caution. An example of an appropriate use 
is a pop-up menu. 

Advice to Implementors 

The user will not be able to move, resize, restack, or transfer the input focus to 
override-redirect windows, since the window manager is not managing them. 

If it is necessary for a client to receive keystrokes on an override-redirect win- 
dow, either the client must grab the keyboard or the client must have another 
top-level window that is not override-redirect and that has selected the Locally 
Active or Globally Active focus model. The client may set the focus to the 
override-redirect window when the other window receives a 
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WM_TAKE_FOCUS message or one of the events listed in section 4. 1 .7 in the 
description of the Globally Active focus model. 

Window managers are free to decide if WM_TRANSIENT_FOR windows should be iconified 
when the window they are transient for is. Clients displaying WM_TRANSIENT_FOR windows 
that have (or request to have) the window they are transient for iconified do not need to request 
that the same operation be performed on the WM_TRANSIENT_FOR window; the window man- 
ager will change its state if that is the policy it wishes to enforce. 

4.1.11. Window Groups 

A set of top-level windows that should be treated from the user’s point of view as related (even 
though they may belong to a number of clients) should be linked together using the win- 
dow_group field of the WM_HtNTS structure. 

One of the windows (that is, the one the others point to) will be the group leader and will carry 
the group as opposed to the individual properties. Window managers may treat the group leader 
differently from other windows in the group. For example, group leaders may have the full set of 
decorations, and other group members may have a restricted set. 

It is not necessary that the client ever map the group leader; it may be a window that exists solely 
as a placeholder. 

It is up to the window manager to determine the policy for treating the windows in a group. At 
present, there is no way for a client to request a group, as opposed to an individual, operation. 

4.2. Client Responses to Window Manager Actions 

The window manager performs a number of operations on client resources, primarily on their top- 
level windows. Clients must not try to fight this but may elect to receive notification of the win- 
dow manager’s operations. 

4.2.1. Reparenting 

Clients must be aware that some window managers will reparent their top-level windows so that a 
window that was created as a child of the root will be displayed as a child of some window 
belonging to the window manager. The effects that this reparenting will have on the client are as 
follows: 

• The parent value returned by a QueryTree request will no longer be the value supplied to 
the Create Window request that created the reparented window. There should be no need 
for the client to be aware of the identity of the window to which the top-level window has 
been reparented. In particular, a client that wishes to create further top-level windows 
should continue to use the root as the parent for these new windows. 

• The server will interpret the (x,y) coordinates in a Configure Window request in the new 
parent’s coordinate space. In fact, they usually will not be interpreted by the server because 
a reparenting window manager usually will have intercepted these operations (see section 
4.2.2). Clients should use the root coordinate space for these requests (see section 4.1.5). 

• Configure Window requests that name a specific sibling window may fail because the win- 
dow named, which used to be a sibling, no longer is after the reparenting operation (see sec- 
tion 4.1.5). 

• The (x,y) coordinates returned by a GetGeometry request are in the parent’s coordinate 
space and are thus not directly useful after a reparent operation. 

• A background of ParentRelative will have unpredictable results. 

• A cursor of None will have unpredictable results. 

Clients that want to be notified when they are reparented can select for StructureNotify events 
on their top-level window. They will receive a ReparentNotify event if and when reparenting 


39 



Inter- Client Communication Conventions 


Xll, Release 6.4 


takes place. When a client withdraws a top-level window, the window manager will reparent it 
back to the root window if the window had been reparented elsewhere. 

If the window manager reparents a client’s window, the reparented window will be placed in the 
save-set of the parent window. This means that the reparented window will not be destroyed if 
the window manager terminates and will be remapped if it was unmapped. Note that this applies 
to all client windows the window manager reparents, including transient windows and client icon 
windows. 

4.2.2. Redirection of Operations 

Clients must be aware that some window managers will arrange for some client requests to be 
intercepted and redirected. Redirected requests are not executed; they result instead in events 
being sent to the window manager, which may decide to do nothing, to alter the arguments, or to 
perform the request on behalf of the client. 

The possibility that a request may be redirected means that a client cannot assume that any redi- 
rectable request is actually performed when the request is issued or is actually performed at all. 
The requests that may be redirected are Map Window, Configure Window, and Circulate- 
Window. 


Advice to Implementors 

The following is incorrect because the Map Window request may be intercepted and 
the Poly Line output made to an unmapped window: 

MapWindow A 

PolyLine A GC <point> <point> . . . 

The client must wait for an Expose event before drawing in the window . 14 

This next example incorrectly assumes that the ConfigureWindow request is actually 
executed with the arguments supplied: 

ConfigureWindow width=N height=M 
<output assuming window is N by M> 

The client should select for StructureNotify on its window and monitor the window’s size 
by tracking ConfigureNotify events. 

Clients must be especially careful when attempting to set the focus to a window that they 
have just mapped. This sequence may result in an X protocol error: 

MapWindow B 
SetlnputFocus B 

If the MapWindow request has been intercepted, the window will still be unmapped, caus- 
ing the SetlnputFocus request to generate the error. The solution to this problem is for 
clients to select for VisibilityChange on the window and to delay the issuance of the 
SetlnputFocus request until they have received a VisibilityNotify event indicating that the 
window is visible. 

This technique does not guarantee correct operation. The user may have iconified the win- 
dow by the time the SetlnputFocus request reaches the server, still causing an error. Or 
the window manager may decide to map the window into Iconic state, in which case the 
window will not be visible. This will delay the generation of the VisibilityNotify event 
indefinitely. Clients must be prepared to handle these cases. 

14 This is true even if the client set the backing-store attribute to Always. The backing-store attribute is a only a hint, and the server may 
stop maintaining backing store contents at any time. 
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A window with the override-redirect bit set is immune from redirection, but the bit should be set 
on top-level windows only in cases where other windows should be prevented from processing 
input while the override-redirect window is mapped (see section 4.1.10) and while responding to 
ResizeRequest events (see section 4.2.9). 

Clients that have no non-Withdrawn top-level windows and that map an override-redirect top- 
level window are taking over total responsibility for the state of the system. It is their responsibil- 
ity to: 

• Prevent any preexisting window manager from interfering with their activities 

• Restore the status quo exactly after they unmap the window so that any preexisting window 
manager does not get confused 

In effect, clients of this kind are acting as temporary window managers. Doing so is strongly dis- 
couraged because these clients will be unaware of the user interface policies the window manager 
is trying to maintain and because their user interface behavior is likely to conflict with that of less 
demanding clients. 

4.2.3. Window Move 

If the window manager moves a top-level window without changing its size, the client will 
receive a synthetic ConfigureNotify event following the move that describes the new location in 
terms of the root coordinate space. Clients must not respond to being moved by attempting to 
move themselves to a better location. 

Any real ConfigureNotify event on a top-level window implies that the window’s position on the 
root may have changed, even though the event reports that the window’s position in its parent is 
unchanged because the window may have been reparented. Note that the coordinates in the event 
will not, in this case, be directly useful. 

The window manager will send these events by using a SendEvent request with the following 
arguments: 


Argument 

Value 

destination: 

The client’s window 

propagate: 

False 

event-mask: 

StructureNotify 


4.2.4. Window Resize 

The client can elect to receive notification of being resized by selecting for StructureNotify 
events on its top-level windows. It will receive a ConfigureNotify event. The size information 
in the event will be correct, but the location will be in the parent window (which may not be the 
root). 

The response of the client to being resized should be to accept the size it has been given and to do 
its best with it. Clients must not respond to being resized by attempting to resize themselves to a 
better size. If the size is impossible to work with, clients are free to request to change to the 
Iconic state. 

4.2.5. Iconify and Deiconify 

A top-level window that is not Withdrawn will be in the Normal state if it is mapped and in the 
Iconic state if it is unmapped. This will be true even if the window has been reparented; the win- 
dow manager will unmap the window as well as its parent when switching to the Iconic state. 

The client can elect to be notified of these state changes by selecting for StructureNotify events 
on the top-level window. It will receive a UnmapNotify event when it goes Iconic and a Map- 
Notify event when it goes Normal. 
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4.2.6. Colormap Change 

Clients that wish to be notified of their colormaps being installed or uninstalled should select for 
ColormapNotify events on their top-level windows and on any windows they have named in 
WM_COLORMAP_WINDOWS properties on their top-level windows. They will receive Col- 
ormapNotify events with the new field FALSE when the colormap for that window is installed or 
uninstalled. 

4.2.7. Input Focus 

Clients can request notification that they have the input focus by selecting for FocusChange 
events on their top-level windows; they will receive Focusln and FocusOut events. Clients that 
need to set the input focus to one of their subwindows should not do so unless they have set 
WM_TAKE_FOCUS in their WM_PROTOCOLS property and have done one of the following: 

• Set the input field of WM_HINTS to True and actually have the input focus in one of then- 
top-level windows 

• Set the input field of WM_HINTS to False and have received a suitable event as described 
in section 4.1.7 

• Have received a WM_TAKE_FOCUS message as described in section 4.1.7 

Clients should not warp the pointer in an attempt to transfer the focus; they should set the focus 
and leave the pointer alone. For further information, see section 6.2. 

Once a client satisfies these conditions, it may transfer the focus to another of its windows by 
using the SetlnputFocus request, which is defined as follows: 

SetlnputFocus 

focus-. WINDOW or PointerRoot or None 
revert-to: {Parent, PointerRoot, None} 
time : TIMESTAMP or CurrentTime 


Conventions 

1. Clients that use a SetlnputFocus request must set the time argument to the time- 
stamp of the event that caused them to make the attempt. This cannot be a Focusln 
event because they do not have timestamps. Clients may also acquire the focus with- 
out a corresponding EnterNotify event. Clients must not use CurrentTime for the 
time argument. 

2. Clients that use a SetlnputFocus request to set the focus to one of their windows 
must set the revert-to field to Parent. 


4.2.8. ClientMessage Events 

There is no way for clients to prevent themselves being sent ClientMessage events. 

Top-level windows with a WM_PROTOCOLS property may be sent ClientMessage events spe- 
cific to the protocols named by the atoms in the property (see section 4. 1.2.7). For all protocols, 
the ClientMessage events have the following: 

• WM_PROTOCOLS as the type field 

• Format 32 

• The atom that names their protocol in the data[0] field 

• A timestamp in their data[l] field 

The remaining fields of the event, including the window field, are determined by the protocol. 
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These events will be sent by using a SendEvent request with the following arguments: 


Argument 

Value 

destination: 

The client’s window 

propagate: 

False 

event-mask: 

() empty 

event: 

As specified by the protocol 


4.2.8.I. Window Deletion 

Clients, usually those with multiple top-level windows, whose server connection must survive the 
deletion of some of their top-level windows, should include the atom WM_DELETE_WINDOW 
in the WM_PROTOCOLS property on each such window. They will receive a ClientMessage 
event as described above whose data[0] field is WM_DELETE_WINDOW. 

Clients receiving a WM_DELETE_WINDOW message should behave as if the user selected 
“delete window” from a hypothetical menu. They should perform any confirmation dialog with 
the user and, if they decide to complete the deletion, should do the following: 

• Either change the window’s state to Withdrawn (as described in section 4.1.4) or destroy the 
window. 

• Destroy any internal state associated with the window. 

If the user aborts the deletion during the confirmation dialog, the client should ignore the mes- 
sage. 

Clients are permitted to interact with the user and ask, for example, whether a file associated with 
the window to be deleted should be saved or the window deletion should be cancelled. Clients 
are not required to destroy the window itself; the resource may be reused, but all associated state 
(for example, backing store) should be released. 

If the client aborts a destroy and the user then selects DELETE WINDOW again, the window 
manager should start the WM_DELETE_WINDOW protocol again. Window managers should 
not use Destroy Window requests on a window that has WM_DELETE_WINDOW in its 
WM_PROTOCOLS property. 

Clients that choose not to include WM_DELETE_WINDOW in the WM_PROTOCOLS property 
may be disconnected from the server if the user asks for one of the client’s top-level windows to 
be deleted. 

4.2.9. Redirecting Requests 

Normal clients can use the redirection mechanism just as window managers do by selecting for 
SubstructureRedirect events on a parent window or ResizeRedirect events on a window itself. 
However, at most, one client per window can select for these events, and a convention is needed 
to avoid clashes. 

Convention 

Clients (including window managers) should select for SubstructureRedirect and 
ResizeRedirect events only on windows that they own. 

In particular, clients that need to take some special action if they are resized can select for Resize- 
Redirect events on their top-level windows. They will receive a ResizeRequest event if the win- 
dow manager resizes their window, and the resize will not actually take place. Clients are free to 
make what use they like of the information that the window manager wants to change their size, 
but they must configure the window to the width and height specified in the event in a timely 
fashion. To ensure that the resize will actually happen at this stage instead of being intercepted 
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and executed by the window manager (and thus restarting the process), the client needs temporar- 
ily to set override-redirect on the window. 


Convention 

Clients receiving ResizeRequest events must respond by doing the following: 

• Setting override-redirect on the window specified in the event 

• Configuring the window specified in the event to the width and height specified in the 
event as soon as possible and before making any other geometry requests 

• Clearing override-redirect on the window specified in the event 

If a window manager detects that a client is not obeying this convention, it is free to take whatever 
measures it deems appropriate to deal with the client. 

4.3. Communication with the Window Manager by Means of Selections 

For each screen they manage, window managers will acquire ownership of a selection named 
WM_Sn, where n is the screen number, as described in section 1.2.6. Window managers should 
comply with the conventions for “Manager Selections” described in section 2.8. The intent is for 
clients to be able to request a variety of information or services by issuing conversion requests on 
this selection. Window managers should support conversion of the following target on their man- 
ager selection: 

Atom Type Data Received 

VERSION INTEGER Two integers, which are the major and minor release 

numbers (respectively) of the ICCCM with which the 
window manager complies. For this version of the 
ICCCM, the numbers are 2 and 0. 15 


4.4. Summary of Window Manager Property Types 

The window manager properties are summarized in the following table (see also section 14. 1 of 
Xlib - C Language X Interface). 


Name 

Type 

Format 

See Section 

WM CLASS 

STRING 

8 

4.1. 2.5 

WM_CLIENT_MACHINE 

TEXT 


4.1.2.9 

WM COLORMAP WINDOWS 

WINDOW 

32 

4.1. 2.8 

WM HINTS 

WM HINTS 

32 

4. 1.2.4 

WM ICON NAME 

TEXT 


4. 1.2.2 

WM_ICON_SIZE 

WM ICON SIZE 

32 

4.1. 3.2 

WM_NAME 

TEXT 


4. 1.2.1 

WM NORMAL HINTS 

WM SIZE HINTS 

32 

4.1. 2.3 

WM_PROTOCOLS 

ATOM 

32 

4. 1.2.7 

WM STATE 

WM STATE 

32 

4.1. 3.1 

WM TRANSIENT FOR 

WINDOW 

32 

4. 1.2.6 


15 As a special case, clients not wishing to implement a selection request may simply issue a GetSelectionOwner request on the appro- 
priate WM_Sn selection. If this selection is owned, clients may assume that the window manager complies with ICCCM version 2.0 or later. 
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5. Session Management and Additional Inter-Client Exchanges 

This section contains some conventions for clients that participate in session management. See X 
Session Management Protocol for further details. Clients that do not support this protocol cannot 
expect their window state (e.g., WM_STATE, position, size, and stacking order) to be preserved 
across sessions. 

5.1. Client Support for Session Management 

Each session participant will obtain a unique client identifier (client-ID) from the session man- 
ager. The client must identify one top-level window as the “client leader.” This window must be 
created by the client. It may be in any state, including the Withdrawn state. The client leader 
window must have a SM_CLIENT_ID property, which contains the client-ID obtained from the 
session management protocol. That property must: 

• Be of type STRING 

• Be of format 8 

• Contain the client-ID as a string of XPCS characters encoded using ISO 8859-1 

All top-level, nontransient windows created by a client on the same display as the client leader 
must have a WM_CLDENT_LEADER property. This property contains a window ID that identi- 
fies the client leader window. The client leader window must have a WM_CLIENT_LEADER 
property containing its own window ID (i.e., the client leader window is pointing to itself). Tran- 
sient windows need not have a WM_CLIENT_LEADER property if the client leader can be 
deter mi ned using the information in the WM_TRANSIENT_FOR property. The 
WM_CLIENT_LEADER property must: 

• Be of type WINDOW 

• Be of format 32 

• Contain the window ID of the client leader window 

A client must withdraw all of its top-level windows on the same display before modifiying either 
the WM_CLIENT_LEADER or the SM_CLIENT_ID property of its client leader window. 

It is necessary that other clients be able to uniquely identify a window (across sessions) among all 
windows related to the same client-ID. For example, a window manager can require this unique 
ID to restore geometry information from a previous session, or a workspace manager could use it 
to restore information about which windows are in which workspace. A client may optionally 
provide a WM_WINDOW_ROLE property to uniquely identify a window within the scope speci- 
fied above. The combination of SM_CLIENT_ID and WM_WINDOW_ROLE can be used by 
other clients to uniquely identify a window across sessions. 

If the WM_WINDOW_ROLE property is not specified on a top-level window, a client that needs 
to uniquely identify that window will try to use instead the values of WM_CLASS and 
WM_NAME. If a client has multiple windows with identical WM_CLASS and WM_NAME 
properties, then it should provide a WM_WINDOW_ROLE property. 

The client must set the WM_WINDOW_ROLE property to a string that uniquely identifies that 
window among all windows that have the same client leader window. The property must: 

• Be of type STRING 

• Be of format 8 

• Contain a string restricted to the XPCS characters, encoded in ISO 8859-1 

5.2. Window Manager Support for Session Management 

A window manager supporting session management must register with the session manager and 
obtain its own client-ID. The window manager should save and restore information such as the 
WM_STATE, the layout of windows on the screen, and their stacking order for every client win- 
dow that has a valid SM_CLIENT_ID property (on itself, or on the window named by 
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WM_CLIENT_LEADER) and that can be uniquely identified. Clients are allowed to change this 
state during the first phase of the session checkpoint process. Therefore, window managers 
should request a second checkpoint phase and save clients’ state only during that phase. 

5.3. Support for ICE Client Rendezvous 

The Inter-Client Exchange protocol (ICE) defined as of XI 1R6 specifies a generic communica- 
tion framework, independent of the X server, for data exchange between arbitrary clients. ICE 
also defines a protocol for any two ICE clients who also have X connections to the same X server 
to locate (rendezvous with) each other. 

This protocol, called the "ICE X Rendezvous" protocol, is defined in the ICE specification, 
Appendix B, and uses the property ICE_PROTOCOLS plus ClientMessage events. Refer to that 
specification for complete details. 

6. Manipulation of Shared Resources 

X Version 1 1 permits clients to manipulate a number of shared resources, for example, the input 
focus, the pointer, and colormaps. Conventions are required so that clients share resources in an 
orderly fashion. 

6.1. The Input Focus 

Clients that explicitly set the input focus must observe one of two modes: 

• Locally active mode 

• Globally active mode 

Conventions 

1. Locally active clients should set the input focus to one of their windows only when it 
is already in one of their windows or when they receive a WM_TAKE_FOCUS mes- 
sage. They should set the input field of the WM_HINTS structure to True. 

2. Globally active clients should set the input focus to one of their windows only when 
they receive a button event and a passive-grabbed key event, or when they receive a 
WM_TAKE_FOCUS message. They should set the input field of the WM_HINTS 
structure to False . 

3. In addition, clients should use the timestamp of the event that caused them to attempt 
to set the input focus as the time field on the SetlnputFocus request, not 

CurrentTime . 


6.2. The Pointer 

In general, clients should not warp the pointer. Window managers, however, may do so (for 
example, to maintain the invariant that the pointer is always in the window with the input focus). 
Other window managers may want to preserve the illusion that the user is in sole control of the 
pointer. 

Conventions 

1 . Clients should not warp the pointer. 

2. Clients that insist on warping the pointer should do so only with the src-window 
argument of the WarpPointer request set to one of their windows. 
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6.3. Grabs 

A client’s attempt to establish a button or a key grab on a window will fail if some other client has 
already established a conflicting grab on the same window. The grabs, therefore, are shared 
resources, and their use requires conventions. 

In conformance with the principle that clients should behave, as far as possible, when a window 
manager is running as they would when it is not, a client that has the input focus may assume that 
it can receive all the available keys and buttons. 

Convention 

Window managers should ensure that they provide some mechanism for their clients 
to receive events from all keys and ah buttons, except for events involving keys 
whose KeySyms are registered as being for window management functions (for 
example, a hypothetical WINDOW KeySym). 

In other words, window managers must provide some mechanism by which a client can receive 
events from every key and button (regardless of modifiers) unless and until the X Consortium reg- 
isters some KeySyms as being reserved for window management functions. Currently, no 
KeySyms are registered for window management functions. 

Even so, clients are advised to allow the key and button combinations used to elicit program 
actions to be modified, because some window managers may choose not to observe this conven- 
tion or may not provide a convenient method for the user to transmit events from some keys. 

Convention 

Clients should establish button and key grabs only on windows that they own. 

In particular, this convention means that a window manager that wishes to establish a grab over 
the client’s top-level window should either establish the grab on the root or reparent the window 
and establish the grab on a proper ancestor. In some cases, a window manager may want to con- 
sume the event received, placing the window in a state where a subsequent such event will go to 
the client. Examples are: 

• Clicking in a window to set focus with the click not being offered to the client 

• Clicking in a buried window to raise it, again, with the click not offered to the client 

More typically, a window manager should add to, rather than replace, the client’s semantics for 
key+button combinations by allowing the event to be used by the client after the window manager 
is done with it. To ensure this, the window manager should establish the grab on the parent by 
using the following: 

pointer/keyboard-mode == Synchronous 

Then, the window manager should release the grab by using an AllowE vents request with the 
following specified: 

mode == ReplayPointer/Keyboard 

In this way, the client will receive the events as if they had not been intercepted. 

Obviously, these conventions place some constraints on possible user interface policies. There is 
a trade-off here between freedom for window managers to implement their user interface policies 
and freedom for clients to implement theirs. The dilemma is resolved by: 

• Allowing window managers to decide if and when a client will receive an event from any 
given key or button 

• Placing a requirement on the window manager to provide some mechanism, perhaps a 
“Quote” key, by which the user can send an event from any key or button to the client 
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6.4. Colormaps 

Section 4.1.8 prescribes conventions for clients to communicate with the window manager about 
their colormap needs. If your clients are DirectColor type applications, you should consult sec- 
tion 14.3 of Xlib - C Language X Interface for conventions connected with sharing standard col- 
ormaps. They should look for and create the properties described there on the root window of the 
appropriate screen. 

The contents of the RGB_COLOR_MAP type property are as follows: 


Field 

Type 

Comments 

colormap 

COLORMAP 

ID of the colormap described 

red_max 

CARD32 

Values for pixel calculations 

red_mult 

CARD32 


green_max 

CARD32 


green_mult 

CARD32 


blue_max 

CARD32 


blue_mult 

CARD32 


base_pixel 

CARD32 


visual id 

VISUALID 

Visual to which colormap belongs 

kill_id 

CARD32 

ID for destroying the resources 


When deleting or replacing an RGB_COLOR_MAP, it is not sufficient to delete the property; it is 
important to free the associated colormap resources as well. If kill_id is greater than one, the 
resources should be freed by issuing a KillClient request with kill_id as the argument. If kill_id 
is one, the resources should be freed by issuing a FreeColormap request with colormap as the 
colormap argument. If kill_id is zero, no attempt should be made to free the resources. A client 
that creates an RGB_COLOR_MAP for which the colormap resource is created specifically for 
this purpose should set kill_id to one (and can create more than one such standard colormap using 
a single connection). A client that creates an RGB_COLOR_MAP for which the colormap 
resource is shared in some way (for example, is the default colormap for the root window) should 
create an arbitrary resource and use its resource ID for kill_id (and should create no other stan- 
dard colormaps on the connection). 

Convention 

If an RGB_COLOR_MAP property is too short to contain the visual_id field, it can 
be assumed that the visual_id is the root visual of the appropriate screen. If an 
RGB_COLOR_MAP property is too short to contain the kill_id field, a value of zero 
can be assumed. 

During the connection handshake, the server informs the client of the default colormap for each 
screen. This is a colormap for the root visual, and clients can use it to improve the extent of col- 
ormap sharing if they use the root visual. 

6.5. The Keyboard Mapping 

The X server contains a table (which is read by GetKeyboardMapping requests) that describes 
the set of symbols appearing on the corresponding key for each keycode generated by the server. 
This table does not affect the server’s operations in any way; it is simply a database used by 
clients that attempt to understand the keycodes they receive. Nevertheless, it is a shared resource 
and requires conventions. 

It is possible for clients to modify this table by using a ChangeKeyboardMapping request. In 
general, clients should not do this. In particular, this is not the way in which clients should imple- 
ment key bindings or key remapping. The conversion between a sequence of keycodes received 
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from the server and a string in a particular encoding is a private matter for each client (as it must 
be in a world where applications may be using different encodings to support different languages 
and fonts). See the Xlib reference manual for converting keyboard events to text. 

The only valid reason for using a ChangeKeyboardMapping request is when the symbols writ- 
ten on the keys have changed as, for example, when a Dvorak key conversion kit or a set of APL 
keycaps has been installed. Of course, a client may have to take the change to the keycap on 
trust. 

The following illustrates a permissible interaction between a client and a user: 

Client: “You just started me on a server without a Pause key. Please choose a key to be the 

Pause key and press it now.” 

User: Presses the Scroll Lock key 

Client: “Adding Pause to the symbols on the Scroll Lock key: Confirm or Abort.” 

User: Confirms 

Client: Uses a ChangeKeyboardMapping request to add Pause to the keycode that already 

contains Scroll Lock and issues this request, “Please paint Pause on the Scroll Lock 
key.” 


Convention 

Clients should not use ChangeKeyboardMapping requests. 

If a client succeeds in changing the keyboard mapping table, all clients will receive 
MappingNotify(request==Key board) events. There is no mechanism to avoid receiving these 
events. 


Convention 

Clients receiving MappingNotify(request==Keyboard) events should update any 
internal keycode translation tables they are using. 


6.6. The Modifier Mapping 

X Version 1 1 supports 8 modifier bits of which 3 are preassigned to Shift, Lock, and Control. 
Each modifier bit is controlled by the state of a set of keys, and these sets are specified in a table 
accessed by GetModifierMapping and SetModifierMapping requests. This table is a shared 
resource and requires conventions. 

A client that needs to use one of the preassigned modifiers should assume that the modifier table 
has been set up correctly to control these modifiers. The Lock modifier should be interpreted as 
Caps Lock or Shift Lock according as the keycodes in its controlling set include XK_Caps_Lock 
or XK_Shift_Lock. 


Convention 

Clients should determine the meaning of a modifier bit from the KeySyms being used 
to control it. 

A client that needs to use an extra modifier (for example, META) should do the following: 

• Scan the existing modifier mappings. If it finds a modifier that contains a keycode whose set 
of KeySyms includes XK_Meta_L or XK_Meta_R, it should use that modifier bit. 

• If there is no existing modifier controlled by XK_Meta_L or XK_Meta_R, it should select 
an unused modifier bit (one with an empty controlling set) and do the following: 

- If there is a keycode with XL_Meta_L in its set of KeySyms, add that keycode to the 

set for the chosen modifier. 
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- If there is a keycode with XL_Meta_R in its set of KeySyms, add that keycode to the 
set for the chosen modifier. 

- If the controlling set is still empty, interact with the user to select one or more keys to 
be META. 

• If there are no unused modifier bits, ask the user to take corrective action. 

Conventions 

1 . Clients needing a modifier not currently in use should assign keycodes carrying suit- 
able KeySyms to an unused modifier bit. 

2. Clients assigning their own modifier bits should ask the user politely to remove his or 
her hands from the key in question if their SetModifierMapping request returns a 
Busy status. 

There is no good solution to the problem of reclaiming assignments to the five nonpreassigned 
modifiers when they are no longer being used. 

Convention 

The user must use xmodmap or some other utility to deassign obsolete modifier 
mappings by hand. 

When a client succeeds in performing a SetModifierMapping request, all clients will receive 
MappingNotify(request==Modifier) events. There is no mechanism for preventing these events 
from being received. A client that uses one of the nonpreassigned modifiers that receives one of 
these events should do a GetModifierMapping request to discover the new mapping, and if the 
modifier it is using has been cleared, it should reinstall the modifier. 

Note that a GrabServer request must be used to make the GetModifierMapping and SetModi- 
fierMapping pair in these transactions atomic. 

7. Device Color Characterization 

The X protocol provides explicit Red, Green, and Blue (RGB) values, which are used to directly 
drive a monitor, and color names. RGB values provide a mechanism for accessing the full capa- 
bilities of the display device, but at the expense of having the color perceived by the user remain 
unknowable through the protocol. Color names were originally designed to provide access to a 
device-independent color database by having the server vendor tune the definitions of the colors 
in that textual database. Unfortunately, this still does not provide the client any way of using an 
existing device-independent color, nor for the client to get device-independent color information 
back about colors that it has selected. 

Furthermore, the client must be able to discover which set of colors are displayable by the device 
(the device gamut), both to allow colors to be intelligently modified to fit within the device capa- 
bilities (gamut compression) and to enable the user interface to display a representation of the 
reachable color space to the user (gamut display). 

Therefore, a system is needed that will provide full access to device-independent color spaces for 
X clients. This system should use a standard mechanism for naming the colors, be able to pro- 
vide names for existing colors, and provide means by which unreachable colors can be modified 
to fall within the device gamut. 

We are fortunate in this area to have a seminal work, the 1931 CIE color standard, which is nearly 
universally agreed upon as adequate for describing colors on CRT devices. This standard uses a 
tri-stimulus model called CIE XYZ in which each perceivable color is specified as a triplet of 
numbers. Other appropriate device-independent color models do exist, but most of them are 
directly traceable back to this original work. 
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X device color characterization provides device-independent color spaces to X clients. It does 
this by providing the barest possible amount of information to the client that allows the client to 
construct a mapping between CIE XYZ and the regular X RGB color descriptions. 

Device color characterization is defined by the name and contents of two window properties that, 
together, permit converting between CIE XYZ space and linear RGB device space (such as stan- 
dard CRTs). Linear RGB devices require just two pieces of information to completely character- 
ize them: 

• A 3 x 3 matrix M and its inverse M _1 , which convert between XYZ and RGB intensity 
{RGB intemity ) . 

Osfont]I]ize]u’RGB intensity R][eq] M R][mu] XYZOrfont] 

Osfontjl] ize] u’ XYZ R][eq] M r][i RPiu] RGB intensity 0rfont] 

• A way of mapping between RGB intensity and RGB protocol value. XDCCC supports 
three mechanisms which will be outlined later. 

If other device types are eventually necessary, additional properties will be required to describe 
them. 

7.1. XYZ <-> RGB Conversion Matrices 

Because of the limited dynamic range of both XYZ and RGB intensity, these matrices will be 
encoded using a fixed-point representation of a 32-bit two’s complement number scaled by 2 27 , 
giving a range of -16 to 16 - e, where e = 2 -27 . 

These matrices will be packed into an 18-element list of 32-bit values, XYZ — > RGB matrix first, 
in row major order and stored in the XDCCC_LINEAR_RGB_MATRICES properties (format = 
32) on the root window of each screen, using values appropriate for that screen. 

This will be encoded as shown in the following table: 


XDCCC_LINEAR_RGB_MATRICES property contents 


Field 

Type 

Comments 

M 0 ,o 

INT32 

Interpreted as a fixed-point number -16 < x < 16 

M 0 ,i 

INT32 


M 33 

ENT32 


0 

INT32 


M- 1 0,1 

INT32 


M ' 3,3 

INT32 



7.2. Intensity o RGB Value Conversion 

XDCCC provides two representations for describing the conversion between RGB intensity and 
the actual X protocol RGB values: 

0 RGB value/RGB intensity level pairs 

1 RGB intensity ramp 

In both cases, the relevant data will be stored in the XDCCC_LINEAR_RGB_CORRECTION 
properties on the root window of each screen, using values appropriate for that screen, in what- 
ever format provides adequate resolution. Each property can consist of multiple entries concate- 
nated together, if different visuals for the screen require different conversion data. An entry with 
a VisuallD of 0 specifies data for all visuals of the screen that are not otherwise explicitly listed. 
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The first representation is an array of RGB value/intensity level pairs, with the RGB values in 
strictly increasing order. When converting, the client must linearly interpolate between adjacent 
entries in the table to compute the desired value. This allows the server to perform gamma cor- 
rection itself and encode that fact in a short two-element correction table. The intensity will be 
encoded as an unsigned number to be interpreted as a value between 0 and 1 (inclusive). The pre- 
cision of this value will depend on the format of the property in which it is stored (8, 16, or 32 
bits). For 16-bit and 32-bit formats, the RGB value will simply be the value stored in the prop- 
erty. When stored in 8-bit format, the RGB value can be computed from the value in the property 

Osfont]I]ize]u’RGB value R][eq] 

Because the three electron guns in the device may not be exactly alike in response characteristics, 
it is necessary to allow for three separate tables, one each for red, green, and blue. Therefore, 
each table will be preceded by the number of entries in that table, and the set of tables will be pre- 
ceded by the number of tables. When three tables are provided, they will be in red, green, blue 
order. 

This will be encoded as shown in the following table: 

XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 0 Correction 


Field 

Type 

Comments 

VisuallDO 

CARD 

Most significant portion of VisuallD 

VisuallD 1 

CARD 

Exists if and only if the property format is 8 

VisualID2 

CARD 

Exists if and only if the property format is 8 

VisualID3 

CARD 

Least significant portion, exists if and only if the 
property format is 8 or 16 

type 

CARD 

0 for this type of correction 

count 

CARD 

Number of tables following (either 1 or 3) 

length 

CARD 

Number of pairs - 1 following in this table 

value 

CARD 

X Protocol RGB value 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of length+1 pairs of value/intensity values 

lengthg 

CARD 

Number of pairs - 1 following in this table (if and 
only if count is 3) 

value 

CARD 

X Protocol RGB value 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of lengthg +1 pairs of value/intensity values 

lengthb 

CARD 

Number of pairs - 1 following in this table (if and 
only if count is 3) 

value 

CARD 

X Protocol RGB value 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of lengthb+1 pairs of value/intensity values 


The VisuallD is stored in 4, 2, or 1 pieces, depending on whether the property format is 8, 16, or 
32, respectively. The VisuallD is always stored most significant piece first. Note that the length 
fields are stored as one less than the actual length, so 256 entries can be stored in format 8. 


The second representation is a simple array of intensities for a linear subset of RGB values. The 
expected size of this table is the bits-per-rgb-value of the screen, but it can be any length. This is 
similar to the first mechanism, except that the RGB value numbers are implicitly defined by the 
index in the array (indices start at 0): 


Osfont]I]ize]u’RGB value R][eq] 


Array Index R][mu] R16R]5R]5R]3R]5 
Array Size R][mi] RJ? 
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When converting, the client may linearly interpolate between entries in this table. The intensity 
values will be encoded just as in the first representation. 

This will be encoded as shown in the following table: 

XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 1 Correction 


Field 

Type 

Comments 

VisuallDO 

CARD 

Most significant portion of VisuallD 

Visual ID 1 

CARD 

Exists if and only if the property format is 8 

VisualID2 

CARD 

Exists if and only if the property format is 8 

VisualID3 

CARD 

Least significant portion, exists if and only if the 
property format is 8 or 16 

type 

CARD 

1 for this type of correction 

count 

CARD 

Number of tables following (either 1 or 3) 

length 

CARD 

Number of elements - 1 following in this table 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of length+1 intensity elements 

lengthg 

CARD 

Number of elements - 1 following in this table (if 
and only if count is 3) 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of lengthg +1 intensity elements 

lengthb 

CARD 

Number of elements - 1 following in this table (if 
and only if count is 3) 

intensity 

CARD 

Interpret as a number 0 < intensity < 1 

Total of lengthb+1 intensity elements 


8. Conclusion 

This document provides the protocol-level specification of the minimal conventions needed to 
ensure that X Version 1 1 clients can interoperate properly. This document specifies interoperabil- 
ity conventions only for the X Version 1 1 protocol. Clients should be aware of other protocols 
that should be used for better interoperation in the X environment. The reader is referred to X 
Session Management Protocol for information on session management, and to Inter-Client 
Exchange Protocol for information on general-purpose communication among clients. 

8.1. The X Registry 

The X Consortium maintains a registry of certain X-related items, to aid in avoiding conflicts and 
in sharing of such items. Readers are encouraged to use the registry. The classes of items kept in 
the registry that are relevant to the ICCCM include property names, property types, selection 
names, selection targets, WM_PROTOCOLS protocols, CUentMessage types, and application 
classes. Requests to register items, or questions about registration, should be addressed to 

xregistry@x.org 

or to 

Registry 
X Consortium 
201 Broadway 
Cambridge, MA 02139-1955 
USA 

Electronic mail will be acknowledged upon receipt. Please allow up to 4 weeks for a formal 
response to registration and inquiries. 
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The registry is published as part of the X software distribution from the X Consortium. All regis- 
tered items must have the postal address of someone responsible for the item or a reference to a 
document describing the item and the postal address of where to write to obtain the document. 
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Appendix A 


A. Revision History 

This appendix describes the revision history of this document and summarizes the incompatibili- 
ties between this and earlier versions. 

A.l. The XI 1R2 Draft 

The February 25, 1988, draft that was distributed as part of X Version 11, Release 2, was clearly 
labeled as such, and many areas were explicitly labeled as liable to change. Nevertheless, in the 
revision work done since then, we have been very careful not to introduce gratuitous incompati- 
bility. As far as possible, we have tried to ensure that clients obeying the conventions in the 
XI 1R2 draft would still work. 

A.2. The July 27, 1988, Draft 

The Consortium review was based on a draft dated July 27, 1988. This draft included several 
areas in which incompatibilities with the XI 1R2 draft were necessary: 

• The use of property None in ConvertSelection requests is no longer allowed. Owners that 
receive them are free to use the target atom as the property to respond with, which will work 
in most cases. 

• The protocol for INCREMENTAL type properties as selection replies has changed, and the 
name has been changed to INCR. Selection requestors are free to implement the earlier pro- 
tocol if they receive properties of type INCREMENTAL. 

• The protocol for INDIRECT type properties as selection replies has changed, and the name 
has been changed to MULTIPLE. Selection requestors are free to implement the earlier pro- 
tocol if they receive properties of type INDIRECT. 

• The protocol for the special CLIPBOARD client has changed. The earlier protocol is subject 
to race conditions and should not be used. 

• The set of state values in WM_HINTS.initial_state has been reduced, but the values that are 
still valid are unchanged. Window managers should treat the other values sensibly. 

• The methods an application uses to change the state of its top-level window have changed 
but in such a way that cases that used to work will still work. 

• The x, y, width, and height fields have been removed from the WM_NORMAL_HINTS 
property and replaced by pad fields. Values set into these fields will be ignored. The posi- 
tion and size of the window should be set by setting the appropriate window attributes. 

• A pair of base fields and a win_gravity field have been added to the WM JSTORMALJHINTS 
property. Window managers will assume values for these fields if the client sets a short 
property. 

A.3. The Public Review Drafts 

The Consortium review resulted in several incompatible changes. These changes were included 
in drafts that were distributed for public review during the first half of 1989. 

• The messages field of the WM_HINTS property was found to be unwieldy and difficult to 
evolve. It has been replaced by the WMJPROTOCOLS property, but clients that use the ear- 
lier mechanism can be detected because they set the messages bit in the flags field of the 
WM_HINTS property, and window managers can provide a backwards compatibility mode. 

• The mechanism described in the earlier draft by which clients installed their own subwindow 
colormaps could not be made to work reliably and mandated some features of the look and 
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feel. It has been replaced by the WM_COLORMAP_WINDOWS property. Clients that use 
the earlier mechanism can be detected by the WM_COLORMAPS property they set on their 
top-level window, but providing a reliable backwards compatibility mode is not possible. 

• The recommendations for window manager treatment of top-level window borders have 
been changed as those in the earlier draft produced problems with Visibility events. For non- 
window manager clients, there is no incompatibility. 

• The pseudoroot facility in the earlier draft has been removed. Although it has been success- 
fully implemented, it turns out to be inadequate to support the uses envisaged. An extension 
will be required to support these uses fully, and it was felt that the maximum freedom should 
be left to the designers of the extension. In general, the previous mechanism was invisible to 
clients and no incompatibility should result. 

• The addition of the WM_DELETE_WINDOW protocol (which prevents the danger that 
multi-window clients may be terminated unexpectedly) has meant some changes in the 
WM_SAVE_YOURSELF protocol, to ensure that the two protocols are orthogonal. Clients 
using the earlier protocol can be detected (see WM_PROTOCOLS above) and supported in a 
backwards compatibility mode. 

• The conventions in Section 14.3.1. of Xlib - C Language X Interface regarding properties of 
type RGB_COLOR_MAP have been changed, but clients that use the earlier conventions 
can be detected because their properties are 4 bytes shorter. These clients will work cor- 
rectly if the server supports only a single Visual or if they use only the Visual of the root. 
These are the only cases in which they would have worked, anyway. 

A.4. Version 1.0, July 1989 

The public review resulted in a set of mostly editorial changes. The changes in version 1.0 that 

introduced some degree of incompatibility with the earlier drafts are: 

• A new section (6.3) was added covering the window manager’s use of Grabs. The restric- 
tions it imposes should affect only window managers. 

• The TARGETS selection target has been clarified, and it may be necessary for clients to add 
some entries to their replies. 

• A selection owner using INCR transfer should no longer replace targets in a MULTIPLE 
property with the atom INCR. 

• The contents of the ClientMessage event sent by a client to iconify itself has been clarified, 
but there should be no incompatibility because the earlier contents would not in fact have 
worked. 

• The border-width in synthetic ConfigureNotify events is now specified, but this should not 
cause any incompatibility. 

• Clients are now asked to set a border-width on all Configure Window requests. 

• Window manager properties on icon windows now will be ignored, but there should be no 
incompatibility because there was no specification that they be obeyed previously. 

• The ordering of real and synthetic ConfigureNotify events is now specified, but any incom- 
patibility should affect only window managers. 

• The semantics of WM_SAVE_YOURSELF have been clarified and restricted to be a check- 
point operation only. Clients that were using it as part of a shutdown sequence may need to 
be modified, especially if they were interacting with the user during the shutdown. 

• A kill_id field has been added to RGB_COLOR_MAP properties. Clients using earlier con- 
ventions can be detected by the size of their RGB_COLOR_MAP properties, and the cases 
that would have worked will still work. 
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A.5. Version 1.1 

Version 1.1 was released with X11R5 in September 1991. In addition to some minor editorial 

changes, there were a few semantic changes since Version 1.0: 

• The section on Device Color Characterization was added. 

• The meaning of the NULL property type was clarified. 

• Appropriate references to Compound Text were added. 

A.6. Public Review Draft, December 1993 

The following changes have been made in preparing the public review draft for Version 2.0. 

• [P01] Addition of advice to clients on how to keep track of a top-level window’s absolute 
position on the screen. 

• [P03] A technique for clients to detect when it is safe to reuse a top-level window has been 
added. 

• [P06] Section 4.1.8, on colormaps, has been rewritten. A new feature that allows clients to 
install their own colormaps has also been added. 

• [P08] The LENGTH target has been deprecated. 

• [PI 1] The manager selections facility was added. 

• [PI 7] The definition of the aspect ratio fields of the WM_NORMAL_HINTS property has 
been changed to include the base size. 

• [PI 9] StaticGravity has been added to the list of values allowed for the win_gravity field of 
the WM_HINTS property. The meaning of the CenterGravity value has been clarified. 

• [P20] A means for clients to query the ICCCM compliance level of the window manager has 
been added. 

• [P22] The definition of the MULTIPLE selection target has been clarified. 

• [P25] A definition of “top-level window” has been added. The WM_STATE property has 
been defined and exposed to clients. 

• [P26] The definition of window states has been clarified and the wording regarding window 
state changes has been made more consistent. 

• [P27] Clarified the rules governing when window managers are required to send synthetic 
ConfigureNotify events. 

• [P28] Added a recommended technique for setting the input focus to a window as soon as it 
is mapped. 

• [P29] The required lifetime of resource IDs named in window manager properties has been 
specified. 

• [P30] Advice for dealing with keystrokes and override-redirect windows has been added. 

• [P31] A statement on the ownership of resources transferred through the selection mecha- 
nism has been added. 

• [P32] The definition of the CLIENT_WINDOW target has been clarified. 

• [P33] A rule about requiring the selection owner to reacquire the selection under certain cir- 
cumstances has been added. 

• [P42] Added several new selection targets. 

• [P44] Ambiguous wording regarding the withdrawal of top-level windows has been 
removed. 

• [P45] A facility for requestors to pass parameters during a selection request has been added. 

• [P49] A convention on discrimated names has been added. 
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• [P57] The C_STRING property type was added. 

• [P62] An ordering requirement on processing selection requests was added. 

• [P63] The VisibleHint flag was added. 

• [P64] The session management section has been updated to align with the new session man- 
agement protocol. The old session management conventions have been moved to Appendix 
C. 

• References to the never-forthcoming Window and Session Manager Conventions Manual 
have been removed. 

• Information on the X Registry and references to the session management and ICE docu- 
ments have been added. 

• Numerous editorial and typographical improvements have been made. 

A.7. Version 2.0, April 1994 

The following changes have been made in preparation for releasing the final edition of Version 

2.0 with XI 1R6. 

• The PIXMAP selection target has been revised to return a property of type PIXMAP instead 
oftypeDRAWABLE. 

• The session management section has been revised slightly to correspond with the changes to 
the X Session Management Protocol. 

• Window managers are now prohibited from placing CurrentTime in the timestamp field of 
WM_TAKE_FOCUS messages. 

• In the WM_HINTS property, the VisibleHint flag has been renamed to Urgency Hint. Its 
semantics have also been defined more thoroughly. 

• Additional editorial and typographical changes have been made. 
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Appendix B 


B. Suggested Protocol Revisions 

During the development of these conventions, a number of inadequacies have been discovered in 

the core XI 1 protocol. They are summarized here as input to an eventual protocol revision design 

process: 

• There is no way for anyone to find out the last-change time of a selection. The Get- 
SelectionOwner request should be changed to return the last-change time as well as the 
owner. 

• There is no way for a client to find out which selection atoms are valid. 

• There would be no need for WM_TAKE_FOCUS if the Focusln event contained a time- 
stamp and a previous-focus field. This could avoid the potential race condition. There is 
space in the event for this information; it should be added at the next protocol revision. 

• There is a race condition in the InstallColormap request. It does not take a timestamp and 
may be executed after the top-level colormap has been uninstalled. The next protocol revi- 
sion should provide the timestamp in the InstallColormap, UninstallColormap, List- 
InstalledColormaps requests and in the ColormapNotify event. The timestamp should be 
used in a similar way to the last-focus-change time for the input focus. The lack of times- 
tamps in these packets is the reason for restricting colormap installation to the window man- 
ager. 

• The protocol needs to be changed to provide some way of identifying the Visual and the 
Screen of a colormap. 

• There should be some way to reclaim assignments to the five nonpreassigned modifiers 
when they are no longer needed. The manual method is unpleasantly low-tech. 
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Appendix C 


C. Obsolete Session Manager Conventions 

This appendix contains obsolete conventions for session management using X properties and 
messages. The conventions described here are deprecated and are described only for historical 
interest. For further information on session management, see X Session Management Protocol. 

C.l. Properties 

The client communicates with the session manager by placing two properties (WM_COMMAND 
and WM_CLfENT_MACHINE) on its top-level window. If the client has a group of top-level 
windows, these properties should be placed on the group leader window. 

The window manager is responsible for placing a WM_STATE property on each top-level client 
window for use by session managers and other clients that need to be able to identify top-level 
client windows and their state. 

C.1.1. WM_COMMAND Property 

The WM_COMMAND property represents the command used to start or restart the client. By 
updating this property, clients should ensure that it always reflects a command that will restart 
them in their current state. The content and type of the property depend on the operating system 
of the machine running the client. On POSIX-conformant systems using ISO Latin- 1 characters 
for their command lines, the property should: 

• Be of type STRING 

• Contain a list of null-terminated strings 

• Be initialized from argv 

Other systems will need to set appropriate conventions for the type and contents of 
WM_COMMAND properties. Window and session managers should not assume that 
STRING is the type of WM_COMMAND or that they will be able to understand or display 
its contents. 

Note that WM_COMMAND strings are null-terminated and differ from the general conventions 
that STRING properties are null-separated. This inconsistency is necessary for backwards com- 
patibility. 

A client with multiple top-level windows should ensure that exactly one of them has a 
WM_COMMAND with nonzero length. Zero-length WM_COMMAND properties can be used 
to reply to WM_SAVE_YOURSELF messages on other top-level windows but will otherwise be 
ignored. 

C.1.2. WM_CLIENT_MACHINE Property 

This property is described in section 4. 1.2.9. 

C.2. Termination 

Because they communicate by means of unreliable network connections, clients must be prepared 
for their connection to the server to be terminated at any time without warning. They cannot 
depend on getting notification that termination is imminent or on being able to use the server to 
negotiate with the user about their fate. For example, clients cannot depend on being able to put 
up a dialog box. 

Similarly, clients may terminate at any time without notice to the session manager. When a client 
terminates itself rather than being terminated by the session manager, it is viewed as having 
resigned from the session in question, and it will not be revived if the session is revived. 
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C.3. Client Responses to Session Manager Actions 

Clients may need to respond to session manager actions in two ways: 

• Saving their internal state 

• Deleting a window 

C.3.1. Saving Client State 

Clients that want to be warned when the session manager feels that they should save their internal 
state (for example, when termination impends) should include the atom WM_SAVE_YOURSELF 
in the WM_PROTOCOLS property on their top-level windows to participate in the 
WM_SAVE_YOURSELF protocol. They will receive a ClientMessage event as described in 
section 4.2.8 with the atom WM_SAVE_YOURSELF in its data[0] field. 

Clients that receive WM_SAVE_YOURSELF should place themselves in a state from which they 
can be restarted and should update WM_COMMAND to be a command that will restart them in 
this state. The session manager will be waiting for a PropertyNotify event on WM_COM- 
MAND as a confirmation that the client has saved its state. Therefore, WM_COMMAND should 
be updated (perhaps with a zero-length append) even if its contents are correct. No interactions 
with the user are permitted during this process. 

Once it has received this confirmation, the session manager will feel free to terminate the client if 
that is what the user asked for. Otherwise, if the user asked for the session to be put to sleep, the 
session manager will ensure that the client does not receive any mouse or keyboard events. 

After receiving a WM_SAVE_YOURSELF, saving its state, and updating WM_COMMAND, the 
client should not change its state (in the sense of doing anything that would require a change to 
WM_COMMAND) until it receives a mouse or keyboard event. Once it does so, it can assume 
that the danger is over. The session manager will ensure that these events do not reach clients 
until the danger is over or until the clients have been killed. 

Irrespective of how they are arranged in window groups, clients with multiple top-level windows 
should ensure the following: 

• Only one of their top-level windows has a nonzero-length WM_COMMAND property. 

• They respond to a WM_SAVE_YOURSELF message by: 

- First, updating the nonzero-length WM_COMMAND property, if necessary 

Second, updating the WM_COMMAND property on the window for which they 
received the WM_SAVE_YOURSELF message if it was not updated in the first step 

Receiving WM_SAVE_YOURSELF on a window is, conceptually, a command to save the entire 
client state. 16 

C.3.2. Window Deletion 

Windows are deleted using the WM_DELETE_WINDOW protocol, which is described in section 
4.2.8. 1. 

C.4. Summary of Session Manager Property Types 

The session manager properties are listed in the following table: 


16 This convention has changed since earlier drafts because of the introduction of the protocol in the next section. In the public review 
draft, there was ambiguity as to whether WM_SAVE_YOURSELF was a checkpoint or a shutdown facility. It is now unambiguously a 
checkpoint facility; if a shutdown facility is judged to be necessary, a separate WM_PROTOCOLS protocol will be developed and registered 
with the X Consortium. 
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Name 

Type 

Format 

See Section 

WM CLIENT MACHINE 

TEXT 


4. 1.2.9 

WM COMMAND 

TEXT 


C.1.1 

WM STATE 

WM STATE 

32 

4.1. 3.1 
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Index 


A 

Alloc, 10, 13 
AllowEvents, 47 
Always, 40 
AnyPropertyType, 9 

B 

BlackPixel, 35 
Busy, 50 

ButtonPress, 32, 34 
ButtonRelease, 32, 34 

c 

Center, 23 
CenterGravity, 57 
ChangeKeyboardMapping, 48, 49 
ChangeProperty, 10, 19, 21 
ChangeWindow Attributes, 33 
ChangeProperty, 19 
CirculateWindow, 40 

ClientMessage, 2, 18, 19, 26, 29, 30, 34, 36, 42, 

43, 46, 56, 61 

ClientMessages, 30 

ClientMessage, 19, 53 

ColormapChange, 36 

ColormapNotify, 42 

ColormapNotify, 59 

ConfigureNotify, 31, 32, 33, 41, 56 

ConfigureRequest, 31, 32 

ConfigureWindow, 31, 32, 39, 40, 56 

ConfigureNotify, 40 

ConfigureWindow, 40 

ConvertSelection, 8 , 9, 10, 12, 13, 14, 15, 55 
ConvertSelection, 8, 9 
CopyFromParent, 35 
CreateWindow, 39 

CurrentTime, 4, 5, 6, 8, 34, 42, 46, 58 

D 

DeleteProperty, 10 
DestroyWindow, 43 


DirectColor, 48 

E 

East, 23 

EnterNotify, 32, 34, 42 
Expose, 40 
Exposure, 38 

F 

False, 20, 24, 29, 32, 34, 36, 41, 42, 43, 46 

FocusChange, 42 

Focusln, 34, 42, 59 

FocusOut, 42 

FreeColormap, 48 

G 

GetAtomName, 2 
GetGeometry, 17, 39 
GetKeyboardMapping, 48 
GetModifierMapping, 49, 50 
GetProperty, 9, 10, 17, 19 
GetSelectionOwner, 5, 14, 18, 44 
GetSelectionOwner, 18 
GetSelectionOwner, 59 
GrabServer, 50 

I 

ICE Rendezvous, 46 
IconicState, 24, 28, 29 
IconMaskHint, 24 
IconPixmapHint, 24 
IconPositionHint, 24 
IconWindowHint, 24 
InputHint, 24 
InputOutput, 38 
InstallColormap, 36, 37, 59 
InternAtom, 1,2, 14 
InternAtom, 2 

K 

KeyPress, 32, 34 
KeyRelease, 32, 34 
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KillClient, 48 

L 

LeaveNotify, 32 
ListlnstalledColormaps, 59 

M 

MapNotify, 29, 41 
MappingNotify, 49, 50 
Map Window, 40 
Map Window, 40 
MessageHint, 24 
MotionNotify, 32 

N 

NewValue, 17 

None, 4, 5, 6, 7, 8, 9, 13, 14, 15, 28, 32, 35, 39, 42, 
55 

NormalState, 24, 28, 29 
NormalState, 28 
North, 23 
NorthEast, 23 
Northwest, 22, 23 

P 

Parent, 35, 42 
ParentRelative, 39 
PAspect, 22 
PBaseSize, 22 
Pixmap, 37 
PMaxSize, 22 
PMinSize, 22 
PointerRoot, 33, 35, 42 
PolyLine, 40 
PPosition, 22 
PResizelnc, 22 
PropertyNotify, 7, 17, 61 
PropertyNotify, 5 
PSize, 22 
PWinGravity, 22 

Q 


Replace, 19, 21 
ResizeRedirect, 43 
ResizeRequest, 41, 43, 44 
ResizeRedirect, 38, 43 
RotateProperties, 19 

s 

SelectionClear, 5, 7, 11 
SelectionNotify, 5, 6 , 7, 9, 10, 13, 17 
SelectionRequest, 5, 6, 13 
SelectionClear, 8 
SelectionNotify, 7 
SelectionRequest, 6 

SendEvent, 5, 6, 18, 29, 30, 32, 37, 41, 43 
SendEvent, 36 

SetlnputFocus, 34, 35, 42, 46 
SetlnputFocus, 40 
SetModifierMapping, 49, 50 
SetSelectionOwner,, 4 
SetSelectionOwner, 4, 5, 7, 8, 10 
SetSelectionOwner, 5, 8 
SetSelectionOwner, 5 
South, 23 
SouthEast, 23 
Southwest, 23 
StateHint, 24 
Static, 23 
StaticGravity, 57 

StructureNotify, 18, 29, 31, 39, 41 
StructureNotify, 19, 40 
SubstructureRedirect, 18,43 
SubstructureRedirect|SubstructureNotify, 29, 32 

T 

TranslateCoordinates, 3 1 , 32 
True, 10, 17, 24, 34, 42, 46 

u 

UninstallColormap, 59 
Unmap, 23 

UnmapNotify, 29, 30, 41 
UrgencyHint, 24, 25, 58 
USPosition, 22 
USSize, 22 

V 


QueryTree, 39 

R 

Registry, 53 
ReparentNotify, 30, 39 


VisibilityChange, 30 
VisibilityNotify, 30 
VisibilityChange, 36, 40 
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VisibilityNotify, 40 
VisibleHint, 58 

w 

WarpPointer, 46 
West, 23 
WhitePixel, 35 
WindowGroupHint, 24 
WithdrawnState, 28 
WithdrawnState, 28 
wmtalk, 8 

X 

X Registry, 53 
xload, 33 
xmodmap, 50 
XSetErrorHandler, 10 


Map Window, 40 



Extended Window Manager 

Hints 


1 . Introduction 

1.1. Version 

This spec is version 1.0. 

1.2. What is this spec? 

This spec defines interactions between window managers, applications and the utilities 
that form part of a desktop environment. It builds on the ICCCM [2], which defines 
wm/client interactions at a lower level. It was bom out of a need to replace the original 
Gnome WM specification, although this specification has been designed to be 
independent of any one desktop environment. 


1.3. Language used in this specification 

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 
this document are to be interpreted as described in RFC 2119. 

The key words "Window Manager" refer to a window manager which is adopting this 
specification. "Pager" refers to desktop utility applications, including pagers and 
taskbars. "Application" refers to other clients. "Clients" refers to Pagers + Applications 
ie. all X clients, except for the Window Manager. 


1 



Extended Window Manager Hints 


1.4. Prerequisites for adoption of this specification 

Window Managers and Clients which aim to fulfil this specification MUST adhere to 
the ICCCM on which this specification builds. If this specification explicitly modifies 
the ICCCM Window Managers and Clients MUST fulfil these modifications. 


2. Non-ICCCM features 

There is a number of window management features or behaviours which are not 
specified in the ICCCM, but are commonly met in modem Window Managers and 
Desktop Environments. 

2.1. Additional States 

The ICCCM allows Window Managers to implement additional window states, which 
will appear to clients as substates of NormalState and IconicState. Two commonly met 
examples are Maximized and Shaded. A Window Manager may implement these as 
proper substates of NormalState and IconicState, or it may treat them as independent 
flags, allowing e.g. a maximized window to be iconified and to re-appear as maximized 
upon de-iconification. 

2.1.1. Maximization 

Maximization is a very old feature of Window Managers. There was even a 
ZoomedState in early ICCCM drafts. Maximizing a window should give it as much of 
the screen area as possible (this may not be the full screen area, but only a smaller 
’workarea’, since the Window Manager may have reserved certain areas for other 
windows). A Window Manager is expected to remember the geometry of a maximized 
window and restore it upon de-maximization. Modem Window Managers typically 
allow separate horizontal and vertical maximization. 

With the introduction of the Xinerama extension in XI 1 R6.4, maximization has 
become more involved. Xinerama allows a screen to span multiple monitors in a freely 
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configurable geometry. In such a setting, maximizing a window would ideally not grow 
it to fill the whole screen, but only the monitor it is shown on. There are of course 
borderline cases for windows crossing monitor boundaries, and ’real’ maximization to 
the full screen may sometimes be useful. 


2.1.2. Shading 

Some Desktop Environments offer shading (also known as rollup) as an alternative to 
iconfication. A shaded window typically shows only the titlebar, the client window is 
hidden, thus shading is not useful for windows which are not decorated with a titlebar. 


2.2. Modality 

The Window Manager_TRANSIENT_FOR hint of the ICCCM allows clients to specify 
that a toplevel window may be closed before the client finishes. A typical example of a 
transient window is a dialog. Some dialogs can be open for a long time, while the user 
continues to work in the main window. Other dialogs have to be closed before the user 
can continue to work in the main window. This property is called modality. While 
clients can implement modal windows in an ICCCM compliant way using the globally 
active input model, some Window Managers offer support for handling modality. 


2.3. Large Desktops 

The Window Manager may offer to arrange the managed windows on a desktop that is 
larger than the root window. The screen functions as a viewport on this large desktop. 
Different policies regarding the positioning of the viewport on the desktop can be 
implemented: The Window Manager may only allow to change the viewport position in 
increments of the screen size (paging) or it may allow arbitrary positions (scrolling). 

To fulfill the ICCCM principle that clients should behave the same regardless wether a 
Window Manager is running or not, Window Managers which implement large 
desktops must interpret all client-provided geometries with respect to the current 
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viewport. 

2.3.1. Implementation note 

There are two options for implementing a large desktop: The first is to keep the 
managed windows (or, if reparenting, their frames) as children of the root window. 
Moving the viewport is achieved by moving all managed windows in the opposite 
direction. 

The second alternative is to reparent all managed windows to a dedicated large window 
(somewhat inappropriately called a ’virtual root’). Moving the viewport is then 
achieved by moving the virtual root in the opposite direction. 

Both alternatives are completely ICCCM compliant, although the second one may be 
somewhat problematic for clients trying to figure out the Window Manager decorations 
around their toplevel windows and for clients trying to draw background images on the 
root window. 


2.4. Sticky windows 

A Window Manager which implements a large desktop typically offers a way for the 
user to make certain windows ’stick to the glass’, i.e. these windows will stay at the 
same position on the screen when the viewport is moved. 


2.5. Virtual Desktops 

Most X servers have only a single screen. The Window Manager may virtualize this 
resource and offer multiple so-called ’virtual desktops’, of which only one can be 
shown on the screen at a time. There is some variation among the features of virtual 
desktop implementations. There may be a fixed number of desktops, or new ones may 
be created dynamically. The size of the desktops may be fixed or variable. If the 
desktops are larger than the root window, their viewports (see Section 2.3) may be 
independent or forced to be at the same position. 
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A Window Manager which implements virtual desktops generally offers a way for the 
user to move clients between desktops. Clients may be allowed to occupy more than 
one desktop simultaneously. 

2.5.1. Implementation note 

There are at least two options for implementing virtual desktops. The first is to use 
multiple virtual roots (see Section 2.3.1) and change the current desktop by 
manipulating the stacking order of the virtual roots. This is completely ICCCM 
compliant, but has the issues outlined in Section 2.3.1 

The second option is to keep all managed windows as children of the root window and 
unmap the frames of those which are not on the current desktop. This puts the clients in 
an undefined ICCCM state, since they are unviewable, but not iconic. In practice, this 
seems to cause no problems and the ICCCM compliant alternative to iconify all clients 
on non-current desktops (without showing their icons) is clearly not acceptable. 


2.6. Pagers 

A pager offers a different UI for window management tasks. It shows a miniature view 
of the desktop(s) representing managed windows by small rectangles and allows the 
user to initiate various Window Manager actions by manipulating these representations. 
Typically offered actions are activation (see Section 2.8), moving, restacking, 
iconification, maximization and closing. On a large desktop, the pager may offer a way 
to move the viewport. On virtual desktops, the pager may offer ways to move windows 
between desktops and to change the current desktop. 


2.7. Taskbars 

A taskbar offers another UI for window management tasks. It typically represents client 
windows as a list of buttons labelled with the window titles and possibly icons. 

Pressing a button initiates a Window Manager action on the represented window, 
typical actions being activation and iconification. In environments with a taskbar, icons 
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are often considered inappropriate, since the iconified windows are already represented 
in the taskbar. 


2.8. Activation 

In the X world, activating a window means to give it the input focus. This may not be 
possible if the window is unmapped, because it is on a different desktop. Thus, 
activating a window may involve additional steps like moving it to the current desktop 
(or changing to the desktop the window is on), deiconifying it or raising it. 


2.9. Animated iconification 

Some Window Managers display some form of animation when (de-)iconfying a 
window. This may be a line drawing connecting the comers of the window with the 
comers of the icon or the window may be opaquely moved and resized on some 
trajectory joining the window location and the icon location. 


2.10. Window-in-window MDI 

Window-in-window MDI is a multiple document interface known from MS Windows 
platforms. Programs employing it have a single top-level window which contains a 
workspace which contains the subwindows for the open documents. These subwindows 
are decorated with Window Manager frames and can be manipulated within their 
parent window just like ordinary top-level windows on the root window. 


2.1 1 . Scope of this spec 

This spec tries to address the following issues: 

• Allow clients to influence their initial state with respect to maximization, shading, 
stickyness, desktop. 
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• Improve the Window Managers ability to vary window decorations by allowing 
clients to hint the Window Manager about the type of their windows. 

• Enable pagers and taskbars to be implemented as separate clients and allow them to 
work with any compliant Window Manager. 

This spec doesn’t cover any of the following: 

• Other IPC mechanisms like ICE or Corba. 

• Window Manager configuration. 

• Window Manager documentation. 

• Geometry between desktops. 

• Clients appearing on a proper subset of desktops. 

• Window-in-window MDI. 

The Window Manager is supposed to be in charge of window management policy, so 
that there is consistent behaviour on the user’s screen no matter who wrote the clients. 

The spec offers a lot of external control about Window Manager actions. This is 
intended mainly to allow pagers, taskbars and similar Window Manager UIs to be 
implemented as separate clients. "Ordinary" clients shouldn’t use these except maybe 
in response to a direct user request (i.e. setting a config option to start maximized or 
specifying a -desk n cmdline argument). 


3. Root Window Properties (+Related 
Messages) 

Whenever this spec speaks about “sending a message to the root window”, it is 
understood that the client is supposed to create a ClientMessage event with the specified 
contents and send it by using a SendEvent request with the following arguments: 


destination 

propagate 


root 

False 
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event-mask ( SubstructureNotify | SubstructureRedirect ) 

event the specified ClientMessage 


3.1. _NET_SUPPORTED 

_NET_SUPPORTED , ATOM [ ] / 3 2 

This property MUST be set by the Window Manager to indicate which hints it 
supports. This assumes that backwards incompatible changes will not be made to the 
hints (without being renamed). 


3.2. _NET_CLIENT_LIST 

_NET_CLIENT_LIST, WINDOW!] /32 
_NET_CLIENT_LIST_STACKING , WINDOW [ ] / 3 2 

These arrays contain all X Windows managed by the Window Manager. 
_NET_CLIENT_LIST has initial mapping order, starting with the oldest window. 
_NET_CLIENT_LIST_STACKING has bottom-to-top stacking order. These properties 
SHOULD be set and updated by the Window Manager. 


3.3. NET NUMBER OF DESKTOPS 


_NET_NUMBER_OF_DESKTOPS , CARDINAL / 3 2 

This property SHOULD be set and updated by the Window Manager to indicate the 
number of virtual desktops. 

A Pager can request change in the desktops number by sending a 
_NET_NUMBER_OF_DESKTOPS message to the root window: 

_NET_NUMBER_OF_DESKTOPS 

message_type = _NET_NUMBER_OF_DESKTOPS 
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format -- 32 

data . 1 [ 0 ] = new_number_of_desktops 

The Window Manager is free to honor or reject this request. If request is honored 
_NET_NUMBER_OF_DESKTOPS MUST be set to the new number of desktops, 
_NET_VIRTUAL_ROOTS MUST be set to store the new number of desktop virtual 
root window IDs and _NET_DESKTOP_VIEWPORT and _NET_WORKAREA must 
also be changed accordingly. The _NET_DESKTOP_NAMES property MAY remain 
unchanged. 

If the number of desktops is shrinking and _NET_CURRENT_DESKTOP is out of the 
new range of of available desktops, then this MUST must be set to the last available 
desktop from the new set. If number of desktops is shrinking then clients that are still 
present on desktops, that are out of the new range, MUST be moved to the very last 
desktop from the new set. For these _NET_WM_DESKTOP MUST be updated. 

3.4. _NET_DESKTOP_GEOMETRY 

_NET_DESKTOP_GEOMETRY width, height, CARDINAL [2 ]/ 32 

Array of two cardinals that defines the common size of all desktops. This property 
SHOULD be set by the Window Manager. 

A Pager can request a change in the desktop geometry by sending a 
_NET_DESKTOP_GEOMETRY client message to the root window: 

_NET_DESKTOP_GEOMETRY 

message_type - _NET_DESKTOP_GEOMETRY 

format = 32 

data.l[0] = new_width 

data.lfl] = new_height 

The Window Manager MAY choose to ignore this message, in which case 
_NET_DESKTOP_GEOMETRY property will remain unchanged. 
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3.5. _NET_DESKTOP_VIEWPORT 

_NET_DESKTOP_VIEWPORT x, y, CARDINAL [][ 2 ]/ 32 

Array of pairs of cardinals that define the top left comer of each desktops viewport. For 

window managers that don’t support large desktops, this MUST always be set to (0,0). 

A Pager can request to change the viewport for the current desktop by sending a 

_NET_DESKTOP_VIEWPORT client message to the root window: 

_NET_DESKTOP_VIEWPORT 

message_type - _NET_DESKTOP_VIEWPORT 
format = 32 
data.l[0] = new_vx 
data.lfl] = new_vy 

The Window Manager MAY choose to ignore this message, in which case 

_NET_DESKTOP_VIEWPORT property will remain unchanged. 


3.6. _NET_CURRENT_DESKTOP 

_NET_CURRENT_DESKTOP desktop, CARDINAL/ 3 2 

The index of the current desktop. This is always an integer between 0 and 
_NET_NUMBER_OF_DESKTOPS - 1. This MUST be set and updated by the 
Window Manager If a Pager wants to switch to another virtual desktop, it MUST send a 
_NET_CURRENT_DESKTOP client message to the root window: 

_NET_CURRENT_DE SKTO P 

message_type = _NET_CURRENT_DESKTOP 

format = 32 

data . 1 [ 0 ] = new_index 
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3.7. NET DESKTOP NAMES 


_NET_DESKTOP_NAMES , UTF- 8_STRING [ ] 

The names of all virtual desktops. This is a list of NULL-terminated strings in UTF-8 
[1] encoding. This property MAY be changed by a Pager or the Window Manager at 
any time. 

Note: The number of names could be different from 
_NET_NUMBER_OF_DESKTOPS . If it is less than 

_NET_NUMBER_OF_DESKTOPS - then the desktops with high numbers are 
unnamed. If it is larger than _NET_NUMBER_OF_DESKTOPS, then the excess 
names outside of the _NET_NUMBER_OF_DESKTOPS are considered to be reserved 
in case number of desktops is increased. 

Rationale: The name is not a necessary attribute of a virtual desktop. Thus the 
availability or unavailability of names has no impact on virtual desktop functionality. 
Since names are set by users and users are likely to preset names for a fixed number of 
desktops, it doesn’t make sense to shrink or grow this list when the number of available 
desktops changes. 


3.8. _NET_ACTIVE_WINDOW 

_NET_ACTIVE_WINDOW, WINDOW/ 3 2 

The window ID of the currently active window or None if no window has the focus. 
This is a read-only property set by the window manager. If a client (for example, a 
taskbar) wants to activate another window, it MUST send a 
_NET_ACTIVE_WINDOW client message to the root window: 

_NET_ACTIVE_WINDOW 

window = window to activate 
message_type = _NET_ACTIVE_WINDOW 
format = 32 

data.l[0] = 0 /* may be used later */ 
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3.9. _NET_WORKAREA 

_NET_WORKAREA , x, y, width, height CARDINAL [] [4] /32 

This property MUST be set by WM upon calculating the work area for each desktop. 
Contains a geometry for each desktop. These geometries are specified relative to the 
viewport on each desktop and specify an area that is completely contained within the 
viewport. Work area SHOULD be used by desktop applications to place desktop icons 
appropriately. 

The window manager SHOULD calculate this space by taking the current page minus 
space occupied by dock and panel windows, as indicated by the _NET_WM_STRUT 
property set on client windows. 

3.10. _NET_SUPPORTING_WM_CHECK 

_NET_SUPPORTING_WM_CHECK , WINDOW/ 3 2 

The Window Manager MUST set this property on the root window to be the ID of a 
child window created by the WM, to indicate that a compliant WM is active. The child 
window MUST also have the _NET_SUPPORTING_WM_CHECK property set to the 
ID of the child window. The child window MUST also have the _NET_WM_NAME 
property set to the name of the Window Manager. 

Rationale: The child window is used to distinguish an active window manager from a 
stale _NET_SUPPORTING_WM_CHECK property that happens to point to another 
window. If the _NET_SUPPORTING_WM_CHECK window on the client window is 
missing or not properly set, clients SHOULD assume that no conforming window 
manager is present. 

3.11. _NET_VIRTUAL_ROOTS 

_NET_VIRTUAL_ROOTS , WINDOW [1/32 
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To implement virtual desktops, some window managers reparent client windows to a 
child of the root window. Window managers using this technique MUST set this 
property to a list of IDs for windows that are acting as virtual root windows. This 
property allows background setting programs to work with virtual roots and allows 
clients to figure out the WM frame windows of their windows. 


4. Other Root Window Messages 

4.1. _NET_CLOSE_WINDOW 

_NET_CLOSE_WINDOW 

Pagers wanting to close a window MUST send a _NET_CLOSE_WINDOW client 
message request to the root window: 

_NET_C LOS E_W I NDOW 

window = window to close 
message_type = _NET_CLOSE_WINDOW 
format = 32 

data.l[0] = 0 /* may be used later */ 

The Window Manager MUST then attempt to close the window specified. 

Rationale: A window manager might be more clever than the usual method (send 
WM_DELETE message if the protocol is selected, XKillClient otherwise). It might 
introduce a timeout, for example. Instead of duplicating the code, the Window Manager 
can easily do the job. 


4.2. _NET_WM_MOVERESIZE 

_NET_WM_MOVERE SIZE 

window = window to be moved or resized 
message_type = _NET_WM_MOVERESIZE 


13 



Extended Window Manager Hints 


format = 32 
data.l[0] = x_root 
data.l[l] = y_root 
data. 1 [2] = direction 

This message allows an application to initiate window movement or resizing. This 
allows the application to define its own move and size "grips", whilst letting the 
window manager control the actual move/resize. This means that all moves / resizes 
can happen in a consistent manner as defined by the WM. 

When sending this message, x_root and y_root MUST indicate the position of the 
mouse click with respect to the root window and direction MUST indicate whether this 
is a move or resize event, and if it is a resize event, which edges of the window the size 
grip applies to. 


tdefine _NET_WM_MOVERESIZE_SIZE_TOPLEFT 0 

#def ine _NET_WM_MOVERESIZE_SIZE_TOP 1 

ttdefine _NET_WM_MOVERESIZE_SIZE_TOPRIGHT 2 

ttdefine _NET_WM_MOVERESIZE_SIZE_RIGHT 3 

#def ine _NET_WM_MOVERESIZE_SIZE_BOTTOMRIGHT 4 

#def ine _NET_WM_MOVERESIZE_SIZE_BOTTOM 5 

# define _NET_WM_MOVERES I Z E_S I Z E_BOTTOMLEFT 6 

#def ine _NET_WM_MOVERESIZE_SIZE_LEFT 7 

# define _NET_WM_MOVERESIZE_MOVE 8 /* Move- 

ment only * / 


The client MUST release all grabs on Pointer events, prior to sending such message. 


5. Application Window Properties 

5.1. _NET_WM_NAME 

_NET_WM_NAME , UTF-8_STRING 
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The Client SHOULD set this to the title of the window in UTF-8 encoding. If set, the 
Window Manager should use this in preference to WM_NAME. 


5.2. _NET_WM_VISIBLE_NAME 

_NET_WM_VISIBLE_NAME, UTF-8_STRING 

If the Window Manager displays a window name other than _NET_WM_NAME the 
Window Manager MUST set this to the title displayed in UTF-8 encoding. 

Rationale: For window managers that display a title different from the 
_NET_WM_NAME or WM_NAME of the window (i.e. xterm <1>, xterm <2>, ... is 
shown, but _NET_WM_NAME / WM_NAME is still xterm for each window). This 
property allows taskbars / pagers to display the same title as the window manager. 

5.3. _NET_WM_ICON_NAME 

_NET_WM_ICON_NAME , UTF-8_STRING 

The Client SHOULD set this to the title of the icon for this window in UTF-8 encoding. 
If set, the Window Manager should use this in preference to WM_ICON_NAME. 

5.4. _NET_WM_VISIBLE_ICON_NAME 

_NET_WM_VISIBLE_ICON_NAME , UTF- 8_STRING 

If the Window Manager displays an icon name other than _NET_WM_ICON_NAME 
the Window Manager MUST set this to the title displayed in UTF-8 encoding. 


5.5. NET WM DESKTOP 


NET_WM_DESKTOP <desktop>, CARDINAL/32 
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Cardinal to determine the desktop the window is in (or wants to be) starting with 0 for 
the first desktop. A Client MAY choose not to set this property, in which case the 
Window Manager SHOULD place as it wishes. OxFFEFFFFF indicates that the 
window SHOULD appear on all desktops/workspaces. 

The Window Manager should honor _NET_WM_DESKTOP whenever a withdrawn 
window requests to be mapped. 

A Client can request a change of desktop for a non-withdrawn window by sending a 
_NET_WM_DESKTOP client message to the root window: 

_NET_WM_DE S KTO P 

window = the respective client window 
message_type = _NET_WM_DESKTOP 
format = 32 

data.lfO] = new_desktop 

The Window Manager MUST keep this property updated on all windows. 


5.6. _NET_WM_WINDOW_TYPE 

_NET_WM_WINDOW_TYPE , ATOM [ ] / 3 2 

This MUST be set by the Client before mapping, to a list of atoms indicating the 
functional type of the window. This property SHOULD be used by the window 
manager in determining the decoration, stacking position and other behaviour of the 
window. The Client SHOULD specify window types in order of preference (the first 
being most preferable), but MUST include at least one of the basic window type atoms 
from the list below. This is to allow for extension of the list of types, whilst providing 
default behaviour for window managers that do not recognise the extensions. 

Rationale: This hint is intend to replace the MOTIF hints. One of the objections to the 
MOTIF hints is that they are a purely visual description of the window decoration. By 
describing the function of the window, the window manager can apply consistent 
decoration and behaviour to windows of the same type. Possible examples of behaviour 
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include keeping dock/panels on top or allowing pinnable menus / toolbars to only be 
hidden when another window has focus (NextStep style). 

_NET_WM_WINDOW_TYPE_DESKTOP , ATOM 
_NET_WM_WINDOW_TYPE_DOCK, ATOM 
_NET_WM_WINDOW_TYPE_TOOLBAR, ATOM 
_NET_WM_WINDOW_TYPE_MENU, ATOM 
_NET_WM_WINDOW_TYPE_DIALOG, ATOM 
_NET_WM_WINDOW_TYPE_NORMAL , ATOM 

_NET_WM_WINDOW_TYPE_DESKTOP indicates a desktop feature. This can 
include a single window containing desktop icons with the same dimensions as the 
screen, allowing the desktop environment to have full control of the desktop, without 
the need for proxying root window clicks. 

_NET_WM_WINDOW_TYPE_DOCK indicates a dock or panel feature. Typically a 
window manager would keep such windows on top of all other windows. 

_NET_WM_WINDOW_TYPE_TOOLBAR and 

_NET_WM_WINDOW_TYPE_MENU indicate toolbar and pinnable menu windows, 
respectively. 

_NET_WM_WINDOW_TYPE_DIALOG indicates that this is a dialog window. If 
_NET_WM_WINDOW_TYPE is not set, then windows with 
WM_TRANSIENT_FOR set MUST be taken as this type. 

_NET_WM_WINDOW_TYPE_NORMAL indicates that this is a normal, top-level 
window. Windows with neither _NET_WM_WINDOW_TYPE nor 
WM_TRANSIENT_FOR are set MUST be taken as this type. 

5.7. _NET_WM_STATE 

_NET_WM_STATE, ATOM [ ] 

A list of hints describing the window state. Atoms present in the list MUST be 
considered set, atoms not present in the list MUST be considered not set. The Window 
Manager SHOULD honor _NET_WM_STATE whenever a withdrawn window 
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requests to be mapped. A Client wishing to change the state of a window MUST send a 
_NET_WM_STATE client message to the root window (see below). The Window 
Manager MUST keep this property updated to reflect the current state of the window. 

Possible atoms are: 

_NET_WM_STATE_MODAL , ATOM 
_NET_WM_STATE_STICKY, ATOM 
_NET_WM_STATE_MAXIMIZED_VERT, ATOM 
_NET_WM_S TATE_MAX IM I Z ED_HORZ , ATOM 
_NET_WM_STATE_SHADED , ATOM 
_NET_WM_STATE_SKIP_TASKBAR, ATOM 
_NET_WM_STATE_SKIP_PAGER, ATOM 

An implementation MAY add new atoms to this list. Implementations without 
extensions MUST ignore any unknown atoms, effectively removing them from the list. 
These extension atoms MUST NOT start with the prefix _NET. 

_NET_WM_STATE_MODAL indicates that this is a modal dialog box. The 
WM_TRANSIENT_FOR hint MUST be set to indicate which window the dialog is a 
modal for, or set to the root window if the dialog is a modal for its window group. 

_NET_WM_STATE_STICKY indicates that the Window Manager SHOULD keep the 
window’s position fixed on the screen, even when the virtual desktop scrolls. 

_NET_WM_STATE_MAXIMIZED_ { VERT,HORZ } indicates that the window is 
{ vertically, horizontally } maximised. 

_NET_WM_STATE_SHADED indicates that the window is shaded. 

_NET_WM_SKIP_TASKBAR indicates that the window should not be included on a 
taskbar. 

_NET_WM_SKIP_PAGER indicates that the window should not be included on a 
pager. 

To change the state of a mapped window, a Client MUST send a _NET_WM_STATE 
client message to the root window (window is the respective window, type 
_NET_WM_STATE, format 32, l[0]=<the action, as listed below>, l[l]=<First 
property to alter>, l[2]=<Second property to alter>). This message allows two 
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properties to be changed simultaneously, specifically to allow both horizontal and 
vertical maximisation to be altered together. 1[2] MUST be set to zero if only one 
property is to be changed. 1[0], the action, MUST be one of: 

_NET_WM_STATE_REMOVE 0 /* remove/unset property */ 

_NET_WM_STATE_ADD 1 /* add/ set property */ 

_NET_WM_STATE_TOGGLE 2 /* toggle property */ 

See also the implementation notes on urgency and fixed size windows. 


5.8. NET WM STRUT 


_NET_WM_STRUT, left, right, top, bottom, CARDINAL [ 4 ]/ 3 2 

This property MUST be set by the Client if the window is to reserve space at the edge 
of the screen. The property contains a 4 cardinals specifying the width of the reserved 
area at each border of the screen. The order of the borders is left, right, top, bottom. 

The client MAY change this property anytime, therefore the Window Manager MUST 
watch out for property notify events. 

The purpose of struts is to reserve space at the borders of the desktop. This is very 
useful for a docking area, a taskbar or a panel, for instance. The window manager 
should know about this reserved space in order to be able to preserve the space. Also 
maximized windows should not cover that reserved space. 

Rationale: A simple "do not cover" hint is not enough for dealing with e.g. auto-hide 
panels. 

Notes: An auto-hide panel SHOULD set the strut to be its minimum, hidden size. A 
"comer" panel that does not extend for the full length of a screen border SHOULD only 
set one stmt. 


5.9. _NET_WMJCON_GEOMETRY 

_NET_WM_ICON_GEOMETRY, x, y, width, height, CARDINAL [4] /32 
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This optional property MAY be set by standalone tools like a taskbar or an iconbox. It 
specifies the geometry of a possible icon in case the window is iconified. 

Rationale: This makes it possible for a window manager to display a nice animation 
like morphing the window into its icon. 

5.10. _NET_WM_ICON 

_NET_WM_ICON CARDINAL [] [2+n]/32 

This is an array of possible icons for the client. This specification does not stipulate 
what size these icons should be, but individual desktop environments or toolkits may 
do so. The Window Manager MAY scale any of these icons to an appropriate size. 

This is an array of 32bit packed CARDINAL ARGB with high byte being A, low byte 
being B. First two bytes are width, height. Data is in rows, left to right and top to 
bottom. 


5.1 1 . _NET_WM_PID 

_NET_WM_P I D CARDINAL/ 3 2 

If set, this property MUST contain the process ID of the client owning this window. 
This MAY be used by the Window Manager to kill windows which do not respond to 
the _NET_ WM_PIN G protocol. 

See also the implementation notes on killing hung processes. 


5.12. NET WM HANDLED ICONS 


_NET_WM_HANDLED_I CONS 

This property can be set by clients to indicate that the Window Manager need not 
provide icons for iconified windows, for example if the client is a taskbar and provides 
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buttons for iconified windows. 


6. Window Manager Protocols 

6.1. JNET_WM_PING 

This protocol allows the Window Manager to determine if the Client is still processing 
X events. This can be used by the Window Manager to determine if a window which 
fails to close after being sent WM_DELETE_WINDOW has stopped responding, or 
has stalled for some other reason, such as waiting for user confirmation. A Client 
SHOULD indicate that it is willing to participate in this protocol by listing 
_NET_WM_PING in the WM_PROTOCOLS property of the client window. 

A Window Manager can use this protocol at any time by sending a client message as 
follows: 

type = ClientMessage 

window = the respective client window 
message_type = WM_PROTOCOLS 
format = 32 

data . 1 [ 0 ] = _NET_WM_P ING 
data.l[l] = timestamp 

A participating Client receiving this message MUST send it back to the root window 
immediately, by setting window = root, and calling XSendEvent. The Client MUST 
NOT alter the timestamp, as this can be used by the Window Manager to uniquely 
identify the ping. 

The Window Manager MAY kill the Client (using _NET_WM_PID) if it fails to 
respond to this protocol within a reasonable time. 

See also the implementation notes on killing hung processes. 
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7. Implementation notes 

7.1 . Desktop/workspace model 

This spec assumes a desktop model that consists of one or more completely 
independent desktops which may or may not be larger than the screen area. When a 
desktop is larger than the screen it is left to the window manager if it will implement 
scrolling or paging. 


7.2. File Manager desktop 

This spec suggests implementing the file manager desktop by mapping a desktop-sized 
window (no shape) to all desktops, with _NET_WM_WINDOW_TYPE_DESKTOP. 
This makes the desktop focusable and greatly simplifies implementation of the file 
manager. It is also faster than managing lots of small shaped windows. The file 
manager draws the background on this window. There should be a root property with a 
window handle for use in applications that want to draw the background (xearth). 


7.3. Implementing enhanced support for 
application transient windows 

If the WM_TRANSIENT_FOR property is set to None or Root window, the window 
should be treated as a transient for all other windows in the same group. It has been 
noted that this is a slight ICCCM violation, but as this behaviour is pretty standard for 
many toolkits and window managers, and is extremely unlikely to break anything, it 
seems reasonable to document it as standard. 


7.4. Urgency 

Dialog boxes should indicate their urgency level (information or warning) using the 
urgency bit in the WM_HINTS. flags property, as defined in the ICCCM. 
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7.5. Fixed size windows 

Windows can indicate that they are non-resizable by setting minheight = maxheight and 
minwidth = maxwidth in the ICCCM WM_NORMAL_HINTS property. The Window 
Manager MAY decorate such windows differently. 


7.6. Pagers and Taskbars 

This specification attempts to make reasonable provisions for WM independent pagers 
and taskbars. Window Managers that require / desire additional functionality beyond 
what can be achieved using the mechanisms set out in this specification may choose to 
implement their own pagers, which communicates with the Window Manager using 
further, WM-specific hints, or some other means. 


7.7. Window Movement 

Window manager implementors should refer to the ICCCM for definitive specifications 
of how to handle MapRequest and ConfigureRequest events. However, since these 
aspects of the ICCCM are easily misread, this document offers the following 
clarifications: 

• Window managers MUST honour the win_gravity field of WM_NORMAL_HINTS 
for both MapRequest _and_ ConfigureRequest events [1] 

• Applications are free to change their win_gravity setting at any time 

If application changes its gravity then Window manager should adjust the reference 
point, so that client window will not move as the result. For example if client’s 
gravity was North WestGravity and reference point was at the top-left comer of the 
frame window, then after change of gravity to the SouthEast reference point should 
be adjusted to point to the lower-right comer of the frame. 

• When generating synthetic ConfigureNotify events, the position given MUST be the 
top-left comer of the client window in relation to the origin of the root window (i.e., 
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ignoring win_gravity) [2] 

• XMoveWindow(w,x,y) behaviour depends on the window gravity. Upon receiving a 
request from client application the Window Manager calculates a new reference 
point, based on the client window’s own size, border width and gravity. For given 
client window dimentions (width, height) and border width (bw), the reference point 
will be placed at: 


Gravity: 

ref_x: 

ref_y: 

StaticGravity 

X 

y 

North WestGravity 

x-bw 

y-bw 

NorthGravity 

x+(width/2) 

y-bw 

NorthEastGravity 

x+width+bw 

y-bw 

EastGravity 

x+width+bw 

y+(height/2) 

SouthEastGravity 

x+width+bw 

y+height+bw 

SouthGravity 

x+(width/2) 

y+height+bw 

South WestGravity 

x-bw 

y+height+bw 

WestGravity 

x-bw 

y+(height/2) 

CenterGravity 

x+(width/2) 

y+(height/2) 


The Window manager will use the reference point as calculated above, until next 
XMove Window request. The Window Manager will place frame decorations in the 
following position, based on the window gravity : 

StaticGravity: 

window’s left top comer will be placed at (ref_x,ref_y) 

N orthWestGravity : 

window frame’s left top comer will be placed at (ref_x,ref_y) 

NorthGravity: 

window frame’s top side’s center will be placed at (ref_x,ref_y) 

N orthEastGravity : 
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window frame’s right top comer will be placed at (ref_x,ref_y) 

EastGravity: 

window frame’s right side’s center will be placed at (ref_x,ref_y) 

South WestGravity: 

window frame’s left bottom comer will be placed at (ref_x,ref_y) 

SouthGravity: 

window frame’s bottom side’s center will be placed at (ref_x,ref_y) 

S outhEas tGravity : 

window frame’s right bottom comer will be placed at (ref_x,ref_y) 

WestGravity: 

window frame’s left side’s center will be placed at (ref_x,ref_y) 

CenterGravity: 

window frame’s center will be placed at (ref_x,ref_y) 

• Implementation Note for Application developers: 

When client window is resized - its reference point does not move. So for example if 
window has SouthEastGravity and it is resized - the bottom-right comer of its frame 
will not move but instead top-left comer will be adjusted by the difference in size. 

• Implementation Note for WM developers : 

when calculating reference point at the time of initial placement - initial window’s 
width should be taken into consideration, as if it was the frame for this window. 

[1] ICCCM Version 2.0, §4.1.2.3 and §4.1.5 

[2] ICCCM Version 2.0, §4.2.3 
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7.8. Window-in-Window MDI 

The authors of this specification acknowledge that there is no standard method to allow 
the Window Manager to manage windows that are part of a Window-in-Window MDI 
application. Application authors are advised to use some other form of MDI, or to 
propose a mechanism to be included in the next revision of this specification. 


7.9. Killing Hung Processes 

If processes fail to respond to the _NET_WM_PING protocol _NET_WM_PID may be 
used in combination with the ICCCM specified WM_CLIENT_MACHINE(STRING) 
to attempt to kill a process. 


8. References 

[1] F. Yergeau,"UTF-8, a transformation format of ISO 10646", RFC 2279 

[2] David Rosenthal / Stuart W. Marks "Inter-Client Communication Conventions 
Manual (Version 2.0)", X Consortium Standard, X Version 11, Release 6.3 

9. Copyright 

Copyright (C) 2000 See Contributors List 

Permission is hereby granted, free of charge, to any person obtaining a copy of this 
software and associated documentation files (the "Software"), to deal in the Software 
without restriction, including without limitation the rights to use, copy, modify, merge, 
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons 
to whom the Software is furnished to do so, subject to the following conditions: 

The above copyright notice and this permission notice shall be included in all copies or 
substantial portions of the Software. 
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THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY 
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS 
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT 
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
DEALINGS IN THE SOFTWARE. 


10. Contributors 

Sasha Vasko 
Bradley T. Hughes 
Dominik Vogt 
Havoc Pennington 
Jeff Raven 
Jim Gettys 
John Harper 
Julian Adams 
Matthias Ettrich 
Micheal Rogers 
Nathan Clemons 
Tim Janik 
Tomi Ollila 
Sam Lantinga 
The Rasterman 
Paul Warren 


27 



Extended Window Manager Hints 


Owen Taylor 
Marko Macek 
Greg Badros 
Matthias Clasen 
David Rosenthal 


11. Change history 

11.1. Changes since 1 .0pre5 

• Change history moved to end. 

• UTF-8 Reference updated. 

• Window Gravity information updated. 

• Copyright Added. 

• Minor typo corrections. 

11.2. Changes since 1.0pre4 

• Clarified the interpretation of client-provided geometries on large desktops. 

• Added more explanation for _NET_DESKTOP_NAMES. 

• Added _NET_WM_ICON_NAME and _NET_WM_VISIBLE_ICON_NAME. 

• Tried to improve the wording of _NET_WM_STRUT explanation. 

• Changed _NET_WORKAREA to an array of viewport-relative geometries. 

• Updated list of “dependent” properties for _NET_NUMBER_OF_DESKTOPS to 
include _NET_WORKAREA and _NET_DESKTOP_VIEWPORT. 
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• Tidied formatting of all client messages. 

11.3. Changes since 1.0pre3 

• Added information about common non-ICCCM features. 

• Added explanation of sending messages to the root window. 

• Removed XA_ prefix from type names. 

• Clarified that “mapping order” refers to inital mapping and specify the directions of 
both orders. 

• Clarified that desktops have a common size specified by 
_NET_DESKTOP_GEOMETRY. 

• Rewrote explanation of _NET_DESKTOP_VIEWPORT. 

• Tidied formatting of _NET_CURRENT_DESKTOP. 

• Replaced “window handle” by “window ED”. 

• Tidied formatting of _NET_WORKAREA. 

• Rewrote the motivation for _NET_VIRTUAL_ROOTS. 

• Added advice on Pointer grabs to _NET_WM_MOVERESIZE. 

• Fixed typos in _NET_WM_STATE. 

• Added _NET_WM_STATE_SKIP_PAGER. 

• Tidied formatting of _NET_WM_STRUT. 

• Tidied formatting of _NET_WM_ICON_GEOMETRY. 

11.4. Changes since 1.0pre2 

• _NET_SET_NUMBER_OF_DESKTOPS -> _NET_NUMBER_OF_DESKTOPS 
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for consistency. 

• _NET_WM_VISIBLE_NAME_STRING -> _NET_WM_VISIBLE_NAME for 
consistency. 

• _NET_WM_STATE: added explanation of permitted extensions. Added explanation 
of being set / not set. 

• Spellchecked, corrected various typos. 

• UTF8 -> UTF-8 for consistency. 

• added references to the ICCCM an UTF-8 (incomplete). 

• added data and event formats where missing. 

• clarified _NET_SUPPORTING_WM_CHECK. 

• fixed formatting of _N ET_CLO S E_ W IND O W message. 

11.5. Changes since I.Oprel 

• Removed implementation note concerning Gnome’s (potential) file manager 
behaviour. 

• The Window Movement section of the implementation notes has been revised. 

11.6. Changes since 1.9f 

• Revised revision number for first accepted release 1.9XX -> l.OpreXX. 

• Prerequisites for adoption of this specification added. 

• Tidied formatting of _NET_CURRENT_DESKTOP for consistency. 

• Tidied formatting of _NET_ACTIVE_WINDOW for consistency. Removed doubled 
text. 
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• Tidied formatting of _NET_WM_DESKTOP for consistency. 

• Killing Hung Processes implementation note added. _NET_WM_PID and 
_NET_WM_PING now link to this. 

• Clarified x_root and y_root meaning for _NET_WM_MO VERES IZE . 

• Added contributor list. 

11.7. Changes since 1.9e 

• Added _NET_WM_VISIBLE_NAME_STRING 

• Removed ambiguity from _NET_NUMBER_OF_DESKTOPS and 
_NET_DESKTOP_NAMES in combination. 

• Set _NET_WM_MOVERESIZE format to 32 for consistency. 

• Removed _NET_PROPERTffiS. 

• Removed comment from _NET_WM_MOVERESIZE. 

11.8. Changes since 1.9d 

• Added _NET_VIRTUAL_ROOTS 

• Added note about ICCCM compliant window moves. 

• Added _NET_WM_HANDLED_ICON S 

• Added _NET_SUPPORTING_WM_CHECK 

• Removed degrees of activation 
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11.9. Changes since 1.9c 


• Removed packaging of hints into 2 X properties. Jim Getty s points out that the 
performance gains of fewer round trips can be better achieved using Xlib routines. 

• Clarified that _NET_DESKTOP_VIEWPORT is in pixels 

• _NET_DESKTOP_VIEWPORT is now an array, one for each desktop, to allow for 
different active viewports on different desktops 

• _NET_WM_STRUT now only applies on desktops on which the client is visible 

• Introduced RFC 2119 language, and attempted to clarify the roles of the Window 
Manager, Pagers and Applications 

• Added _NET_WM_NAME 

• _NET_DESKTOP_NAMES now in UTF8 

• Desktops now start from 0 


• Added _NET_WM_PID 

• Added _NET_WM_PING protocol 

• Added _NET_WM_STATE_SKIP_TASKBAR 


11.10. Changes since 1.9b 

• Removed _NET_NUMBER_OF_DESKTOPS client message, as it overlaps 
unnecessarily with _NET_{ INSERT/DELETE }_DESKTOP. 

• Replaced _NET_WM_LAYER and _NET_WM_fflNTS with 
_NET_WM_WINDOW_TYPE functional hint. 

• Changed _NET_WM_STATE to a list of atoms, for extensibility. 

• Expanded description of _NET_WORKAREA and _NET_WM_STRUT. 

• Removed _NET_WM_SIZEMOVE_NOTIFY protocol. 
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Added degrees of activation to _NET_ACTIVE_WINDOW client message 
Added _NET_WM_ICON 

My comments are in [[ ]]. Comments from Marko’s draft are in [[MM: ]] 
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